diff --git a/packages/shared/src/telemetry/README.md b/packages/shared/src/telemetry/README.md index 28125b5ab54..50ae8992b33 100644 --- a/packages/shared/src/telemetry/README.md +++ b/packages/shared/src/telemetry/README.md @@ -120,6 +120,47 @@ value with a salted hash of the per-installation secret. Use `trackAgentTaskRun()` to emit this event. The generated contract remains the authority for its exact dimensions and optionality. +## Cloud Direct Delivery + +Self-hosted installs are unchanged. They post every batch to the collector, +private references stay hashed by `hashPrivateRef()`, and the collector and +its loader apply their anonymization. A self-hosted server never loads +`posthog-node`. + +A Paperclip Cloud stack can send telemetry straight to PostHog instead. The +server turns this on only when the instance is Cloud-managed and +`PAPERCLIP_POSTHOG_PROJECT_TOKEN`, `PAPERCLIP_CLOUD_STACK_ID`, and +`PAPERCLIP_POSTHOG_ENVIRONMENT` are set. +`PAPERCLIP_POSTHOG_DIRECT=0` sends through the collector again. The server owns +this transport (`server/src/services/posthog-direct/`). This package only +exposes the `TelemetryTransport` seam on `TelemetryClient`: + +- With a transport, each flushed batch goes to the transport and never to the + collector. One batch has exactly one sender. +- A transport with `hashesPrivateRefs: false` makes the typed helpers emit raw + task ids. Private source refs (for example a private repository name) are + customer content, not identifiers, so they stay hashed on every path and + `source_ref_hashed` stays `true` for them. +- The transport can capture per-event context at track time. That context is + never added to the collector envelope. + +Cloud is Paperclip's own service under the Cloud terms, so its events carry +real identifiers: raw agent and task ids, the stack id, and the company and +acting user ids when known. Event names, dimension names, metadata keys, the +deterministic event uuid, and enum fallback normalization stay the same as the +collector path, so existing insights keep working. Request headers from the +browser SDK only link an event to a browser session. They never set identity +or grant access. Do not use this path to send fields that are not in the +generated contract. + +On each start, a Cloud server with direct delivery also sends one +`cloud.workspace_started` event and a workspace `$groupidentify`, straight +through the PostHog client. Neither is in the generated contract, and neither +goes through `TelemetryClient` or the collector. The event carries +`install_hash`, the sha256 of the install id, which is the same value the +collector stores as `install_id`. It lets an offline job join a workspace's +pre-switch history. No other event carries `install_hash`. + ### Other Data Paths This document covers Paperclip Telemetry only. The generated Telemetry diff --git a/packages/shared/src/telemetry/client.test.ts b/packages/shared/src/telemetry/client.test.ts index 3ba900cdab5..5a95f2305a3 100644 --- a/packages/shared/src/telemetry/client.test.ts +++ b/packages/shared/src/telemetry/client.test.ts @@ -1,5 +1,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import { TelemetryClient } from "./client.js"; +import { TelemetryClient, type TelemetryOutgoingBatch, type TelemetrySendResult, type TelemetryTransport } from "./client.js"; +import { trackAgentTaskRun, trackCompanyImported } from "./events.js"; import { resolveTelemetryConfig } from "./config.js"; import type { TelemetryConfig, TelemetryDimensions, TelemetryState } from "./types.js"; @@ -626,3 +627,96 @@ describe("TelemetryClient bounded pending-retry store", () => { client.stop(); }); }); + +describe("TelemetryClient transport seam", () => { + afterEach(() => { + vi.restoreAllMocks(); + vi.unstubAllGlobals(); + }); + + function makeTransport(overrides: Partial = {}) { + const send = vi.fn(async (_batch: TelemetryOutgoingBatch): Promise => ({ kind: "ok" })); + const transport: TelemetryTransport = { + hashesPrivateRefs: false, + captureEventContext: vi.fn(() => ({ tag: "ctx" })), + send, + ...overrides, + }; + return { transport, send }; + } + + it("keeps hashing private refs on the default collector path", async () => { + const fetchMock = vi.fn().mockResolvedValue({ ok: true }); + vi.stubGlobal("fetch", fetchMock); + const { client } = makeClient(); + expect(client.privateRefsHashed).toBe(true); + + trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" }); + await client.flush(); + + const body = sentBody(); + expect(body.events[0].dimensions.task_id).toBe(client.hashPrivateRef("task-raw-id")); + expect(body.events[0].dimensions.task_id).not.toBe("task-raw-id"); + expect(Object.keys(body).sort()).toEqual([...CONTRACT_KEYS].sort()); + }); + + it("sends each batch to the transport only, never to the collector", async () => { + const fetchMock = vi.fn().mockResolvedValue({ ok: true }); + vi.stubGlobal("fetch", fetchMock); + const { transport, send } = makeTransport(); + const client = new TelemetryClient( + { enabled: true, endpoint: "http://localhost:9999/ingest" }, + () => TEST_STATE, + "0.0.0-test", + () => 0.5, + transport, + ); + + trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" }); + trackCompanyImported(client, { sourceType: "github", sourceRef: "acme/private", isPrivate: true }); + await client.flush(); + + expect(fetchMock).not.toHaveBeenCalled(); + expect(send).toHaveBeenCalledTimes(1); + const batch = send.mock.calls[0]![0]; + expect(batch.installId).toBe("test-install"); + expect(batch.events.map(({ event }) => event.dimensions)).toEqual([ + { agent_id: "agent-1", state: "succeeded", task_id: "task-raw-id" }, + // Private source refs are customer content and stay hashed on Cloud too. + { source_type: "github", source_ref: client.hashPrivateRef("acme/private"), source_ref_hashed: true }, + ]); + expect(batch.events.map(({ context }) => context)).toEqual([{ tag: "ctx" }, { tag: "ctx" }]); + // The per-event context never leaks into the event object itself. + expect(Object.keys(batch.events[0]!.event).sort()).toEqual(["dimensions", "name", "occurredAt"]); + }); + + it("retries a transport batch with the same events instead of switching sender", async () => { + vi.useFakeTimers(); + try { + const fetchMock = vi.fn().mockResolvedValue({ ok: true }); + vi.stubGlobal("fetch", fetchMock); + vi.spyOn(console, "warn").mockImplementation(() => {}); + const send = vi + .fn<(batch: TelemetryOutgoingBatch) => Promise>() + .mockResolvedValueOnce({ kind: "network" }) + .mockResolvedValue({ kind: "ok" }); + const client = new TelemetryClient( + { enabled: true }, + () => TEST_STATE, + "0.0.0-test", + () => 0.5, + { hashesPrivateRefs: false, send }, + ); + client.track("routine.created", {}); + await client.flush(); + await vi.advanceTimersByTimeAsync(2_000); + + expect(send).toHaveBeenCalledTimes(2); + expect(send.mock.calls[1]![0].batchId).toBe(send.mock.calls[0]![0].batchId); + expect(fetchMock).not.toHaveBeenCalled(); + client.stop(); + } finally { + vi.useRealTimers(); + } + }); +}); diff --git a/packages/shared/src/telemetry/client.ts b/packages/shared/src/telemetry/client.ts index 03a10a5550b..d6534ce8aaa 100644 --- a/packages/shared/src/telemetry/client.ts +++ b/packages/shared/src/telemetry/client.ts @@ -74,6 +74,43 @@ const BATCH_ID_HEX_LENGTH = 32; * so it can be cancelled when the batch is evicted from the bounded store, * otherwise the timer would keep firing for a batch that no longer exists. */ +/** Outcome of delivering one batch, as classified by the client's retry logic. */ +export type TelemetrySendResult = + | { kind: "ok" } + | { kind: "status"; status: number; retryAfterMs?: number } + | { kind: "network" }; + +/** + * One wire-ready batch handed to a custom transport. `events` pairs each event + * with the opaque context the transport captured when the event was tracked. + */ +export interface TelemetryOutgoingBatch { + app: string; + schemaVersion: string; + installId: string; + version: string; + batchId: string; + events: ReadonlyArray<{ event: TelemetryEvent; context: unknown }>; +} + +/** + * Narrow seam for a host that delivers telemetry somewhere other than the + * default collector. When a client has a transport, every flushed batch goes + * to `send` and never to the collector endpoints, so each batch has exactly + * one sender. Without a transport the client behaves exactly as before. + */ +export interface TelemetryTransport { + /** + * Whether typed helpers hash private task ids before emission. The default + * collector path always hashes. Private source refs stay hashed on every + * path, because they are customer content rather than identifiers. + */ + readonly hashesPrivateRefs: boolean; + /** Captures per-event context at track time (for example the acting request). */ + captureEventContext?(): unknown; + send(batch: TelemetryOutgoingBatch): Promise; +} + interface PendingBatch { events: TelemetryEvent[]; batchId: string; @@ -95,6 +132,10 @@ export class TelemetryClient { // `maxPendingRetryBatches`. Insertion order == age (oldest at the front). private pending: PendingBatch[] = []; private readonly retryTimers = new Set>(); + private readonly transport: TelemetryTransport | null; + // Per-event transport context, kept off the event object so the collector + // envelope stays byte-identical whether or not a transport is configured. + private readonly eventContexts = new WeakMap(); constructor( config: TelemetryConfig, @@ -103,12 +144,16 @@ export class TelemetryClient { // Injectable RNG for backoff jitter — defaults to `Math.random`; tests pass // a seeded function for deterministic backoff. Callers keep the 3-arg form. random: () => number = Math.random, + // Optional custom delivery. Omitted on self-hosted installs, which keep the + // default collector path unchanged. + transport?: TelemetryTransport, ) { this.config = config; this.caps = resolveCaps(config); this.stateFactory = stateFactory; this.version = version; this.random = random; + this.transport = transport ?? null; } /** @@ -144,11 +189,15 @@ export class TelemetryClient { if (!this.config.enabled) return; this.getState(); // ensure state is initialised (side-effect: creates state file on first call) - this.queue.push({ + const event: TelemetryEvent = { name: eventName, occurredAt: new Date().toISOString(), dimensions: { ...dimensions } as TelemetryDimensions, - }); + }; + if (this.transport?.captureEventContext) { + this.eventContexts.set(event, this.transport.captureEventContext()); + } + this.queue.push(event); if (this.queue.length >= BATCH_SIZE) { void this.flush(); @@ -269,8 +318,7 @@ export class TelemetryClient { * terminal failure or after `maxAttempts` the batch is dropped-and-logged. */ private async attemptSend(batch: PendingBatch): Promise { - const body = JSON.stringify(this.buildEnvelope(batch.events, batch.batchId)); - const outcome = this.classifyOutcome(await this.postEnvelope(body)); + const outcome = this.classifyOutcome(await this.deliver(batch)); if (outcome.kind === "ok") return; @@ -305,8 +353,26 @@ export class TelemetryClient { }); } + /** Sends one batch through exactly one sender: the transport, or else the collector. */ + private async deliver(batch: PendingBatch): Promise { + const envelope = this.buildEnvelope(batch.events, batch.batchId); + if (!this.transport) return this.postEnvelope(JSON.stringify(envelope)); + try { + return await this.transport.send({ + app: envelope.app, + schemaVersion: envelope.schemaVersion, + installId: envelope.installId, + version: envelope.version, + batchId: envelope.batchId, + events: batch.events.map((event) => ({ event, context: this.eventContexts.get(event) })), + }); + } catch { + return { kind: "network" }; + } + } + private classifyOutcome( - result: { kind: "ok" } | { kind: "status"; status: number; retryAfterMs?: number } | { kind: "network" }, + result: TelemetrySendResult, ): { kind: "ok" } | { kind: "retry"; retryAfterMs?: number } | { kind: "terminal"; status: number } { if (result.kind === "ok") return { kind: "ok" }; if (result.kind === "network") return { kind: "retry" }; @@ -408,9 +474,7 @@ export class TelemetryClient { * surface the last transient status if every endpoint returns one — matching * the pre-retry loop's endpoint-fallback behavior. */ - private async postEnvelope( - body: string, - ): Promise<{ kind: "ok" } | { kind: "status"; status: number; retryAfterMs?: number } | { kind: "network" }> { + private async postEnvelope(body: string): Promise { const endpoints = this.resolveEndpoints(); let lastTransient: { kind: "status"; status: number; retryAfterMs?: number } | undefined; for (const endpoint of endpoints) { @@ -481,6 +545,14 @@ export class TelemetryClient { .slice(0, 16); } + /** + * Whether typed helpers hash private references on this client. Always true + * on the default collector path; only a transport can turn it off. + */ + get privateRefsHashed(): boolean { + return this.transport?.hashesPrivateRefs ?? true; + } + private getState(): TelemetryState { if (!this.state) { this.state = this.stateFactory(); diff --git a/packages/shared/src/telemetry/events.ts b/packages/shared/src/telemetry/events.ts index 78f2031313f..5a8bd387ad9 100644 --- a/packages/shared/src/telemetry/events.ts +++ b/packages/shared/src/telemetry/events.ts @@ -7,6 +7,15 @@ function asEventDimension(value: RawDimension): T { return value as T; } +/** + * Emitted form of a private task reference. The default collector path always + * hashes it with `hashPrivateRef()`. Only a client whose transport declares + * `hashesPrivateRefs: false` (Paperclip Cloud direct delivery) emits the raw id. + */ +function emitPrivateRef(client: TelemetryClient, value: string): string { + return client.privateRefsHashed === false ? value : client.hashPrivateRef(value); +} + export function trackInstallStarted(client: TelemetryClient): void { client.track("install.started", {}); } @@ -28,6 +37,8 @@ export function trackCompanyImported( isPrivate: boolean; }, ): void { + // A private source ref is customer content (for example a private repository + // name), not an identifier. It stays hashed on every path, Cloud included. const ref = dims.isPrivate ? client.hashPrivateRef(dims.sourceRef) : dims.sourceRef; client.track("company.imported", { source_type: asEventDimension(dims.sourceType), @@ -120,7 +131,7 @@ export function trackAgentTaskCompleted( agent_id: dims.agentId, adapter_type: asEventDimension(dims.adapterType), ...(dims.model ? { model: dims.model } : {}), - ...(dims.taskId ? { task_id: client.hashPrivateRef(dims.taskId) } : {}), + ...(dims.taskId ? { task_id: emitPrivateRef(client, dims.taskId) } : {}), }); } @@ -149,7 +160,7 @@ export function trackAgentTaskRun( ...(dims.inputTokens === undefined ? {} : { input_tokens: dims.inputTokens }), ...(dims.outputTokens === undefined ? {} : { output_tokens: dims.outputTokens }), ...(dims.cachedTokens === undefined ? {} : { cached_tokens: dims.cachedTokens }), - ...(dims.taskId ? { task_id: client.hashPrivateRef(dims.taskId) } : {}), + ...(dims.taskId ? { task_id: emitPrivateRef(client, dims.taskId) } : {}), }); } diff --git a/packages/shared/src/telemetry/index.ts b/packages/shared/src/telemetry/index.ts index d6436ffd5ba..39ba76a46c3 100644 --- a/packages/shared/src/telemetry/index.ts +++ b/packages/shared/src/telemetry/index.ts @@ -1,4 +1,5 @@ export { TelemetryClient } from "./client.js"; +export type { TelemetryOutgoingBatch, TelemetrySendResult, TelemetryTransport } from "./client.js"; export { resolveTelemetryConfig, resolveCaps, TELEMETRY_DEFAULTS } from "./config.js"; export type { TelemetryConfigOverrides } from "./config.js"; export { loadOrCreateState } from "./state.js"; @@ -40,5 +41,6 @@ export type { EventDimensionsMap, PaperclipEventName, } from "./generated/paperclip-telemetry.js"; +export { PAPERCLIP_EVENTS, PAPERCLIP_ENUM_DESCRIPTIONS } from "./generated/paperclip-telemetry.js"; export { EVENT_RETENTION_CLASS, RETENTION_DAYS } from "./retention.js"; export type { RetentionClass } from "./retention.js"; diff --git a/scripts/generate-posthog-direct-fixtures.mjs b/scripts/generate-posthog-direct-fixtures.mjs new file mode 100644 index 00000000000..64de4f42974 --- /dev/null +++ b/scripts/generate-posthog-direct-fixtures.mjs @@ -0,0 +1,163 @@ +#!/usr/bin/env node +// Regenerates the Paperclip Cloud direct PostHog delivery fixtures from a +// checkout of the private telemetry-backend repository. +// +// Usage: +// git -C fetch origin +// git -C archive --format=tar --prefix=tb/ origin/HEAD | tar -x -C +// node scripts/generate-posthog-direct-fixtures.mjs /tb +// +// It writes two files under server/src/services/posthog-direct/: +// - enum-fallbacks.generated.ts: the backend's unknown-enum fallback rules +// (`x-normalize.unknown_enum_value`). Enum domains come from the shared +// generated contract, so only the fallback rule lives here. +// - __fixtures__/loader-golden.json: one collector envelope, the canonical +// records the backend ingest produces for it, and the PostHog capture +// messages its loader builds from them. The golden test compares the +// server's direct builder against these messages. +// +// The backend modules used here have no external dependencies, so a plain +// source checkout is enough. No network or AWS access is needed: Firehose and +// DynamoDB are replaced by in-memory test clients the backend already supports. + +import { writeFile, mkdir } from "node:fs/promises"; +import path from "node:path"; +import { pathToFileURL, fileURLToPath } from "node:url"; +import { createRequire } from "node:module"; + +const backendDir = process.argv[2]; +if (!backendDir) { + console.error("usage: node scripts/generate-posthog-direct-fixtures.mjs "); + process.exit(1); +} + +const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const outDir = path.join(repoRoot, "server/src/services/posthog-direct"); +const backendUrl = (rel) => pathToFileURL(path.join(path.resolve(backendDir), rel)).href; + +const manifest = createRequire(import.meta.url)(path.join(path.resolve(backendDir), "src/registry/generated/manifest.json")); + +// --- enum fallback table --------------------------------------------------- +const fallbacks = {}; +for (const [eventName, spec] of Object.entries(manifest.events).sort(([a], [b]) => a.localeCompare(b))) { + const required = new Set(spec.required ?? []); + for (const [key, prop] of Object.entries(spec.properties ?? {})) { + const fallback = prop?.["x-normalize"]?.unknown_enum_value; + if (fallback === undefined) continue; + (fallbacks[eventName] ??= {})[key] = { fallback, required: required.has(key) }; + } +} +const fallbackSource = `// GENERATED by scripts/generate-posthog-direct-fixtures.mjs from the telemetry +// backend's event manifest (x-normalize.unknown_enum_value). DO NOT EDIT. +// Enum domains come from PAPERCLIP_ENUM_DESCRIPTIONS in @paperclipai/shared. + +export const UNKNOWN_ENUM_FALLBACKS = ${JSON.stringify(fallbacks, null, 2)} as const; +`; +await writeFile(path.join(outDir, "enum-fallbacks.generated.ts"), fallbackSource); + +// --- golden loader output ---------------------------------------------------- +const { processV2Ingest, setV2IngestAwsClientsForTest } = await import(backendUrl("src/v2/ingest-core.mjs")); +const { buildPostHogEvent } = await import(backendUrl("src/loader/sinks/posthog.mjs")); + +const NOW = "2026-11-17T12:00:00.000Z"; +const HMAC_SECRET = "fixture-only-hmac-secret"; +const RAW_TASK_ID = "6f1f3c2a-9b8e-4d7c-a1b2-c3d4e5f60718"; +const HASHED_TASK_ID = "9c1e5b7a3d2f4e60"; // what hashPrivateRef emits on the collector path + +const envelope = { + app: "paperclip", + schemaVersion: "1", + installId: "11111111-2222-4333-8444-555555555555", + version: "2026.1117.0", + batchId: "fixture-batch-0001", + events: [ + { name: "server.started", occurredAt: "2026-11-17T11:58:00.000Z", dimensions: { os_platform: "linux" } }, + { + name: "agent.task_run", + occurredAt: "2026-11-17T11:58:01.000Z", + dimensions: { + agent_id: "2f6c7d1e-0a4b-4c3d-9e8f-112233445566", + state: "succeeded", + adapter_type: "claude_local", + agent_role: "engineer", + model: "claude-opus-5-5", + duration_seconds: 42, + input_tokens: 1200, + output_tokens: 300, + task_id: HASHED_TASK_ID, + }, + }, + { + name: "agent.created", + occurredAt: "2026-11-17T11:58:02.000Z", + dimensions: { agent_id: "3a7b8c9d-1e2f-4a5b-8c6d-778899aabbcc", agent_role: "astronaut" }, + }, + { + name: "install.completed", + occurredAt: "2026-11-17T11:58:03.000Z", + dimensions: { adapter_type: "future_adapter" }, + }, + { + name: "skill.imported", + occurredAt: "2026-11-17T11:58:04.000Z", + dimensions: { source_type: "mystery_source" }, + }, + { + name: "interaction.resolved", + occurredAt: "2026-11-17T11:58:05.000Z", + dimensions: { + interaction_kind: "suggest_tasks", + status: "accepted", + resolved_by_kind: "user", + option_count: 3, + selected_option_count: 2, + legacy_inherited_restriction: false, + }, + }, + { name: "routine.created", occurredAt: "2026-11-17T11:58:06.000Z", dimensions: {} }, + { + // Unregistered names are quarantined by the backend and never reach PostHog. + name: "question_response.delivery", + occurredAt: "2026-11-17T11:58:07.000Z", + dimensions: { outcome: "delivered" }, + }, + ], +}; + +const canonicalRecords = []; +setV2IngestAwsClientsForTest({ + firehose: { + async send(command) { + for (const record of command.input.Records ?? []) { + const parsed = JSON.parse(Buffer.from(record.Data).toString("utf-8")); + if (command.input.DeliveryStreamName === "canonical") canonicalRecords.push(parsed); + } + return { FailedPutCount: 0, RequestResponses: [] }; + }, + }, + dynamoDb: { async send() { return {}; } }, +}); +process.env.V2_CANONICAL_FIREHOSE_STREAM_NAME = "canonical"; +process.env.V2_QUARANTINE_FIREHOSE_STREAM_NAME = "quarantine"; +process.env.V2_BATCH_LEDGER_TABLE_NAME = "ledger"; +delete process.env.AGENT_ID_HASH_SECRET; + +const originalInfo = console.info; +console.info = () => {}; // silence the backend's metric lines +const response = await processV2Ingest( + { requestContext: { http: { method: "POST" } }, headers: {}, isBase64Encoded: false, body: JSON.stringify(envelope) }, + { source: "client", route: "/v2/ingest", now: new Date(NOW), deploymentSource: "cloud" }, +); +console.info = originalInfo; +if (response.statusCode !== 202) { + throw new Error(`backend ingest rejected the fixture envelope: ${response.statusCode} ${response.body}`); +} + +const loaderEvents = canonicalRecords.map((record) => buildPostHogEvent(record, { distinctIdHmacSecret: HMAC_SECRET })); + +await mkdir(path.join(outDir, "__fixtures__"), { recursive: true }); +await writeFile( + path.join(outDir, "__fixtures__/loader-golden.json"), + `${JSON.stringify({ ingestedAt: NOW, rawTaskId: RAW_TASK_ID, hashedTaskId: HASHED_TASK_ID, envelope, canonicalRecords, loaderEvents }, null, 2)}\n`, +); +console.log(`wrote ${loaderEvents.length} loader events and ${Object.keys(fallbacks).length} fallback rule sets`); diff --git a/server/package.json b/server/package.json index 73a88325b8b..8abf9dd4b86 100644 --- a/server/package.json +++ b/server/package.json @@ -112,6 +112,7 @@ "pino": "^10.0.0", "pino-http": "^11.0.0", "pino-pretty": "^13.1.3", + "posthog-node": "5.38.2", "sharp": "^0.35.4", "smol-toml": "^1.9.1", "ssh2": "^1.17.0", diff --git a/server/src/__tests__/cloud-posthog-config.test.ts b/server/src/__tests__/cloud-posthog-config.test.ts new file mode 100644 index 00000000000..f34bdb5c833 --- /dev/null +++ b/server/src/__tests__/cloud-posthog-config.test.ts @@ -0,0 +1,81 @@ +import { describe, expect, it } from "vitest"; +import { isPostHogDirectDeliveryEnabled, resolveCloudPostHogConfig } from "../services/cloud-posthog-config.js"; + +const CLOUD = { + PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-token", + PAPERCLIP_CLOUD_STACK_ID: "stack-123", + PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test", +}; + +describe("resolveCloudPostHogConfig", () => { + it("is null on a self-hosted install, even with a PostHog token", () => { + expect(resolveCloudPostHogConfig({})).toBeNull(); + expect( + resolveCloudPostHogConfig({ PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test", PAPERCLIP_CLOUD_STACK_ID: "stack-123" }), + ).toBeNull(); + }); + + it("is null on Cloud without a token or without a stack id", () => { + expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_PROJECT_TOKEN: "" })).toBeNull(); + expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_PROJECT_TOKEN: " " })).toBeNull(); + expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_CLOUD_STACK_ID: undefined })).toBeNull(); + }); + + it("resolves defaults on a Cloud stack with a token", () => { + expect(resolveCloudPostHogConfig(CLOUD)).toEqual({ + token: "phc_test", + host: "https://us.i.posthog.com", + environment: null, + stackId: "stack-123", + directEnabled: true, + browserEnabled: false, + replayEnabled: false, + }); + }); + + it("accepts the legacy managed-config Cloud signal", () => { + const { PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: _omit, ...rest } = CLOUD; + expect(resolveCloudPostHogConfig({ ...rest, PAPERCLIP_MANAGED_CONFIG: "{}" })?.stackId).toBe("stack-123"); + }); + + it("reads host, environment and the switches", () => { + const config = resolveCloudPostHogConfig({ + ...CLOUD, + PAPERCLIP_POSTHOG_HOST: "http://127.0.0.1:9999/", + PAPERCLIP_POSTHOG_ENVIRONMENT: "staging", + PAPERCLIP_POSTHOG_DIRECT: "0", + PAPERCLIP_POSTHOG_BROWSER_ENABLED: "1", + }); + expect(config).toMatchObject({ + host: "http://127.0.0.1:9999", + environment: "staging", + directEnabled: false, + browserEnabled: true, + replayEnabled: true, + }); + }); + + it("turns replay off with its own switch and never without the browser switch", () => { + expect( + resolveCloudPostHogConfig({ + ...CLOUD, + PAPERCLIP_POSTHOG_BROWSER_ENABLED: "1", + PAPERCLIP_POSTHOG_REPLAY_ENABLED: "0", + })?.replayEnabled, + ).toBe(false); + expect(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_REPLAY_ENABLED: "1" })?.replayEnabled).toBe(false); + }); + + it("turns direct delivery on only with the switch on and an environment", () => { + expect(isPostHogDirectDeliveryEnabled(null)).toBe(false); + expect(isPostHogDirectDeliveryEnabled(resolveCloudPostHogConfig(CLOUD))).toBe(false); + expect( + isPostHogDirectDeliveryEnabled(resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_ENVIRONMENT: "staging" })), + ).toBe(true); + expect( + isPostHogDirectDeliveryEnabled( + resolveCloudPostHogConfig({ ...CLOUD, PAPERCLIP_POSTHOG_ENVIRONMENT: "staging", PAPERCLIP_POSTHOG_DIRECT: "0" }), + ), + ).toBe(false); + }); +}); diff --git a/server/src/__tests__/posthog-direct-event-shape.test.ts b/server/src/__tests__/posthog-direct-event-shape.test.ts new file mode 100644 index 00000000000..5ae8e2bf623 --- /dev/null +++ b/server/src/__tests__/posthog-direct-event-shape.test.ts @@ -0,0 +1,109 @@ +import { describe, expect, it } from "vitest"; +import { PAPERCLIP_ENUM_DESCRIPTIONS, type TelemetryEvent } from "@paperclipai/shared/telemetry"; +import golden from "../services/posthog-direct/__fixtures__/loader-golden.json" with { type: "json" }; +import { UNKNOWN_ENUM_FALLBACKS } from "../services/posthog-direct/enum-fallbacks.generated.js"; +import { + buildPostHogDirectEvent, + resolveDistinctId, +} from "../services/posthog-direct/event-shape.js"; + +// The golden fixture is produced by running the telemetry backend's own ingest +// and loader on one collector envelope. Regenerate it with +// `node scripts/generate-posthog-direct-fixtures.mjs `. + +const config = { stackId: "stack-123", environment: "staging" }; +const meta = { + app: golden.envelope.app, + schemaVersion: golden.envelope.schemaVersion, + installId: golden.envelope.installId, + version: golden.envelope.version, + ingestedAt: golden.ingestedAt, +}; + +type LoaderEvent = (typeof golden.loaderEvents)[number]; + +// The Cloud direct path emits the raw task id where the collector path emits +// its salted hash. Everything else in the event is the same input. +function directInput(event: (typeof golden.envelope.events)[number]): TelemetryEvent { + const dimensions = { ...event.dimensions } as Record; + if (dimensions.task_id === golden.hashedTaskId) dimensions.task_id = golden.rawTaskId; + return { name: event.name, occurredAt: event.occurredAt, dimensions }; +} + +describe("Cloud direct PostHog event shape", () => { + const direct = golden.envelope.events.map((event) => + buildPostHogDirectEvent(directInput(event), undefined, meta, config), + ); + const sent = direct.filter((event) => event !== null); + + it("drops exactly the events the backend quarantines", () => { + expect(sent.map((event) => event!.event)).toEqual(golden.loaderEvents.map((event) => event.event)); + expect(direct.find((_, i) => golden.envelope.events[i]!.name === "question_response.delivery")).toBeNull(); + }); + + it("matches the loader output except for the intended Cloud differences", () => { + golden.loaderEvents.forEach((loader: LoaderEvent, index) => { + const ours = sent[index]!; + const inputDims = golden.envelope.events.find((e) => e.name === loader.event)!.dimensions as Record; + const hasPrivateRef = "task_id" in inputDims; + + // Same envelope-level fields; uuid differs only when the dimensions do. + expect(ours.event).toBe(loader.event); + expect(ours.timestamp).toBe(loader.timestamp); + expect(ours.disableGeoip).toBe(loader.disableGeoip); + expect(ours.sendFeatureFlags).toBe(loader.sendFeatureFlags); + if (hasPrivateRef) expect(ours.uuid).not.toBe(loader.uuid); + else expect(ours.uuid).toBe(loader.uuid); + + // Intended differences: real ids and Cloud workspace properties. + const intended = { + distinct_id: "workspace:stack-123", + stack_id: "stack-123", + environment: "staging", + $groups: { workspace: "stack-123" }, + ...("agent_id" in inputDims ? { agent_id: inputDims.agent_id } : {}), + ...(hasPrivateRef ? { task_id: golden.rawTaskId } : {}), + }; + expect(ours.distinct_id).toBe("workspace:stack-123"); + expect(ours.properties).toEqual({ ...loader.properties, ...intended }); + // Key order matches too, so the stored property layout is identical. + expect(Object.keys(ours.properties).slice(0, Object.keys(loader.properties).length - 2)).toEqual( + Object.keys(loader.properties).filter((key) => key !== "distinct_id" && key !== "$process_person_profile"), + ); + }); + }); + + it("uses the acting user as distinct_id and links the browser session", () => { + const event = buildPostHogDirectEvent( + { name: "routine.created", occurredAt: "2026-11-17T11:58:06.000Z", dimensions: {} }, + { userId: "user-1", companyId: "company-1", sessionId: "sess-1", windowId: "win-1" }, + meta, + config, + )!; + expect(event.distinct_id).toBe("user-1"); + expect(event.properties).toMatchObject({ + distinct_id: "user-1", + user_id: "user-1", + company_id: "company-1", + $session_id: "sess-1", + $window_id: "win-1", + $groups: { workspace: "stack-123" }, + }); + expect(event.properties).not.toHaveProperty("$process_person_profile"); + }); + + it("falls back to the workspace id without an acting user", () => { + expect(resolveDistinctId(config, undefined)).toBe("workspace:stack-123"); + expect(resolveDistinctId(config, { companyId: "company-1", sessionId: "sess-1" })).toBe("workspace:stack-123"); + expect(resolveDistinctId(config, { userId: "user-9" })).toBe("user-9"); + }); + + it("keeps every generated fallback rule tied to an enum in the shared contract", () => { + const domains = PAPERCLIP_ENUM_DESCRIPTIONS as Record>>; + for (const [eventName, rules] of Object.entries(UNKNOWN_ENUM_FALLBACKS)) { + for (const [key, rule] of Object.entries(rules)) { + expect(Object.keys(domains[eventName]?.[key] ?? {}), `${eventName}.${key}`).toContain(rule.fallback); + } + } + }); +}); diff --git a/server/src/__tests__/posthog-direct-telemetry.test.ts b/server/src/__tests__/posthog-direct-telemetry.test.ts new file mode 100644 index 00000000000..e18bda622a9 --- /dev/null +++ b/server/src/__tests__/posthog-direct-telemetry.test.ts @@ -0,0 +1,348 @@ +import { createHash } from "node:crypto"; +import { mkdtempSync, readFileSync, rmSync } from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import express from "express"; +import request from "supertest"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { trackAgentTaskRun, trackCompanyImported, trackRoutineCreated } from "@paperclipai/shared/telemetry"; + +const hoisted = vi.hoisted(() => ({ instanceRoot: "", posthogNodeLoads: 0 })); + +vi.mock("../home-paths.js", () => ({ + resolvePaperclipInstanceRoot: () => hoisted.instanceRoot, +})); + +// Counts real loads of the package. Self-hosted servers must never load it. +vi.mock("posthog-node", () => { + hoisted.posthogNodeLoads += 1; + return { PostHog: class {} }; +}); + +import { + getTelemetryClient, + initTelemetry, + isPostHogDirectTelemetryActive, + resetTelemetryForTests, + shutdownTelemetry, +} from "../telemetry.js"; +import type { PostHogNodeClient } from "../services/posthog-direct/index.js"; +import { + capturePostHogEventContext, + postHogRequestContextMiddlewareForEnv, +} from "../services/posthog-direct/request-context.js"; +import { serverVersion } from "../version.js"; + +const COLLECTOR = "http://collector.test/ingest"; +const CLOUD_ENV = { + PAPERCLIP_CLOUD_TENANT_SERVER_TOKEN: "tenant-token", + PAPERCLIP_CLOUD_STACK_ID: "stack-123", + PAPERCLIP_STACK_SLUG: "acme", + PAPERCLIP_PRIMARY_HOST: "acme.paperclip.app", + PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test", + PAPERCLIP_POSTHOG_ENVIRONMENT: "staging", +}; + +function fakePostHog() { + const captured: Array[0]> = []; + const groups: Array[0]> = []; + const client: PostHogNodeClient & { shutdownCalls: number } = { + shutdownCalls: 0, + capture: (message) => void captured.push(message), + groupIdentify: (message) => void groups.push(message), + flush: async () => {}, + shutdown: async () => { + client.shutdownCalls += 1; + }, + }; + const factory = vi.fn(async () => client); + return { client, captured, groups, factory }; +} + +function readState() { + return JSON.parse(readFileSync(path.join(hoisted.instanceRoot, "telemetry", "state.json"), "utf-8")) as { + installId: string; + salt: string; + }; +} + +describe("server telemetry sender selection", () => { + let fetchMock: ReturnType; + + beforeEach(() => { + hoisted.instanceRoot = mkdtempSync(path.join(os.tmpdir(), "paperclip-posthog-direct-")); + hoisted.posthogNodeLoads = 0; + for (const name of ["CI", "CONTINUOUS_INTEGRATION", "BUILD_NUMBER", "GITHUB_ACTIONS", "GITLAB_CI", "DO_NOT_TRACK", "PAPERCLIP_TELEMETRY_DISABLED"]) { + vi.stubEnv(name, ""); + } + vi.stubEnv("PAPERCLIP_TELEMETRY_ENDPOINT", COLLECTOR); + fetchMock = vi.fn().mockResolvedValue({ ok: true }); + vi.stubGlobal("fetch", fetchMock); + }); + + afterEach(() => { + resetTelemetryForTests(); + vi.unstubAllEnvs(); + vi.unstubAllGlobals(); + rmSync(hoisted.instanceRoot, { recursive: true, force: true }); + }); + + it("self-hosted: posts the unchanged hashed envelope to the collector and never loads posthog-node", async () => { + const client = initTelemetry({ enabled: true }, { env: {} })!; + expect(isPostHogDirectTelemetryActive()).toBe(false); + trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" }); + await shutdownTelemetry(); + + expect(hoisted.posthogNodeLoads).toBe(0); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(fetchMock.mock.calls[0]![0]).toBe(COLLECTOR); + const body = String((fetchMock.mock.calls[0]![1] as RequestInit).body); + const parsed = JSON.parse(body); + const state = readState(); + const hashedTaskId = createHash("sha256").update(state.salt + "task-raw-id").digest("hex").slice(0, 16); + // Byte-identical to the envelope the collector path has always sent. + expect(body).toBe( + JSON.stringify({ + app: "paperclip", + schemaVersion: "1", + installId: state.installId, + version: serverVersion, + events: [ + { name: "server.started", occurredAt: parsed.events[0].occurredAt, dimensions: { os_platform: process.platform } }, + { + name: "agent.task_run", + occurredAt: parsed.events[1].occurredAt, + dimensions: { agent_id: "agent-1", state: "succeeded", task_id: hashedTaskId }, + }, + ], + batchId: parsed.batchId, + }), + ); + }); + + it("self-hosted: ignores posthog-js tracing headers", async () => { + expect(postHogRequestContextMiddlewareForEnv({})).toBeNull(); + expect(postHogRequestContextMiddlewareForEnv({ PAPERCLIP_POSTHOG_PROJECT_TOKEN: "phc_test" })).toBeNull(); + const app = express(); + let context: unknown = "unset"; + app.get("/probe", (_req, res) => { + context = capturePostHogEventContext(); + res.json({}); + }); + await request(app).get("/probe").set("X-POSTHOG-SESSION-ID", "sess-1").expect(200); + expect(context).toBeUndefined(); + }); + + it("Cloud: sends each batch only to PostHog with real ids, and identifies the workspace group", async () => { + const posthog = fakePostHog(); + const client = initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory })!; + expect(isPostHogDirectTelemetryActive()).toBe(true); + trackAgentTaskRun(client, { agentId: "agent-1", state: "succeeded", taskId: "task-raw-id" }); + trackCompanyImported(client, { sourceType: "github", sourceRef: "acme/private-repo", isPrivate: true }); + await shutdownTelemetry(); + + expect(fetchMock).not.toHaveBeenCalled(); + expect(posthog.captured.map((message) => message.event).sort()).toEqual([ + "agent.task_run", + "cloud.workspace_started", + "company.imported", + "server.started", + ]); + // A private source ref is customer content: it stays hashed on Cloud too. + const imported = posthog.captured.find((message) => message.event === "company.imported")!; + const salt = readState().salt; + expect(imported.properties).toMatchObject({ + source_ref: createHash("sha256").update(salt + "acme/private-repo").digest("hex").slice(0, 16), + source_ref_hashed: true, + }); + expect(JSON.stringify(imported)).not.toContain("acme/private-repo"); + const run = posthog.captured.find((message) => message.event === "agent.task_run")!; + expect(run.distinctId).toBe("workspace:stack-123"); + expect(run.groups).toEqual({ workspace: "stack-123" }); + expect(run.disableGeoip).toBe(true); + expect(run.properties).toMatchObject({ + agent_id: "agent-1", + task_id: "task-raw-id", + stack_id: "stack-123", + environment: "staging", + deployment_source: "cloud", + $groups: { workspace: "stack-123" }, + $process_person_profile: false, + }); + expect(run.properties).not.toHaveProperty("install_hash"); + + const installHash = createHash("sha256").update(readState().installId).digest("hex"); + const started = posthog.captured.find((message) => message.event === "cloud.workspace_started")!; + expect(started.distinctId).toBe("workspace:stack-123"); + expect(started.groups).toEqual({ workspace: "stack-123" }); + expect(started.properties).toMatchObject({ + app: "paperclip", + schema_version: "1", + source: "client", + deployment_source: "cloud", + version: serverVersion, + stack_id: "stack-123", + install_hash: installHash, + environment: "staging", + distinct_id: "workspace:stack-123", + $process_person_profile: false, + }); + for (const message of posthog.captured) { + expect(message.properties?.environment, message.event).toBe("staging"); + if (message.event !== "cloud.workspace_started") expect(message.properties).not.toHaveProperty("install_hash"); + } + expect(posthog.groups).toEqual([ + { + groupType: "workspace", + groupKey: "stack-123", + disableGeoip: true, + properties: { stack_slug: "acme", primary_host: "acme.paperclip.app", environment: "staging" }, + }, + ]); + expect(posthog.client.shutdownCalls).toBe(1); + }); + + it("Cloud: stays on the collector when PAPERCLIP_POSTHOG_ENVIRONMENT is unset", async () => { + const posthog = fakePostHog(); + const { PAPERCLIP_POSTHOG_ENVIRONMENT: _omit, ...noEnvironment } = CLOUD_ENV; + const client = initTelemetry({ enabled: true }, { env: noEnvironment, postHogFactory: posthog.factory })!; + expect(isPostHogDirectTelemetryActive()).toBe(false); + trackRoutineCreated(client); + await shutdownTelemetry(); + + expect(posthog.factory).not.toHaveBeenCalled(); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(fetchMock.mock.calls[0]![0]).toBe(COLLECTOR); + expect(postHogRequestContextMiddlewareForEnv(noEnvironment)).toBeNull(); + }); + + it("Cloud: the kill switch falls back to the collector", async () => { + const posthog = fakePostHog(); + const client = initTelemetry( + { enabled: true }, + { env: { ...CLOUD_ENV, PAPERCLIP_POSTHOG_DIRECT: "0" }, postHogFactory: posthog.factory }, + )!; + expect(isPostHogDirectTelemetryActive()).toBe(false); + trackRoutineCreated(client); + await shutdownTelemetry(); + + expect(posthog.factory).not.toHaveBeenCalled(); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(postHogRequestContextMiddlewareForEnv({ ...CLOUD_ENV, PAPERCLIP_POSTHOG_DIRECT: "0" })).toBeNull(); + }); + + it("Cloud: links request events to the acting user and browser session", async () => { + const posthog = fakePostHog(); + initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory }); + const middleware = postHogRequestContextMiddlewareForEnv(CLOUD_ENV); + expect(middleware).not.toBeNull(); + + const app = express(); + app.use(middleware!); + app.use((req, _res, next) => { + const as = req.header("x-test-actor"); + req.actor = + as === "user" + ? { type: "board", userId: "user-1", source: "session" } + : as === "agent" + ? { type: "agent", agentId: "agent-1", companyId: "company-1", source: "agent_key" } + : { type: "none", source: "none" }; + next(); + }); + app.post("/companies/:companyId/routines", (_req, res) => { + trackRoutineCreated(getTelemetryClient()!); + res.json({}); + }); + + await request(app) + .post("/companies/company-9/routines") + .set("x-test-actor", "user") + .set("X-POSTHOG-SESSION-ID", "0190f6b2-7c1d-7a3e-9f00-123456789abc") + .set("X-POSTHOG-WINDOW-ID", "0190f6b2-7c1d-7a3e-9f00-abcdefabcdef") + // Never used for identity. + .set("X-POSTHOG-DISTINCT-ID", "spoofed-person") + .expect(200); + await request(app).post("/companies/company-9/routines").set("x-test-actor", "agent").expect(200); + await request(app) + .post("/companies/company-9/routines") + .set("X-POSTHOG-SESSION-ID", "bad id with spaces") + // An anonymous request cannot claim a person through the header either. + .set("X-POSTHOG-DISTINCT-ID", "spoofed-person") + .expect(200); + await shutdownTelemetry(); + + const routines = posthog.captured.filter((message) => message.event === "routine.created"); + expect(routines).toHaveLength(3); + expect(routines[0]!.distinctId).toBe("user-1"); + expect(routines[0]!.properties).toMatchObject({ + user_id: "user-1", + company_id: "company-9", + $session_id: "0190f6b2-7c1d-7a3e-9f00-123456789abc", + $window_id: "0190f6b2-7c1d-7a3e-9f00-abcdefabcdef", + }); + expect(routines[0]!.properties).not.toHaveProperty("$process_person_profile"); + expect(JSON.stringify(routines)).not.toContain("spoofed-person"); + + expect(routines[1]!.distinctId).toBe("workspace:stack-123"); + expect(routines[1]!.properties).toMatchObject({ company_id: "company-1", $process_person_profile: false }); + expect(routines[1]!.properties).not.toHaveProperty("user_id"); + + expect(routines[2]!.distinctId).toBe("workspace:stack-123"); + expect(routines[2]!.properties).not.toHaveProperty("$session_id"); + expect(routines[2]!.properties).not.toHaveProperty("user_id"); + expect(routines[2]!.properties).toMatchObject({ distinct_id: "workspace:stack-123", $process_person_profile: false }); + }); + + it("Cloud: uses a board user's only company on routes without a company id", async () => { + const posthog = fakePostHog(); + initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory }); + const app = express(); + app.use(postHogRequestContextMiddlewareForEnv(CLOUD_ENV)!); + app.use((req, _res, next) => { + const companyIds = req.header("x-test-companies")!.split(","); + req.actor = { type: "board", userId: "user-1", companyIds, source: "cloud_tenant" }; + next(); + }); + app.post("/issues/:id/interactions/:interactionId/reject", (_req, res) => { + trackRoutineCreated(getTelemetryClient()!); + res.json({}); + }); + await request(app).post("/issues/i-1/interactions/x-1/reject").set("x-test-companies", "company-1").expect(200); + await request(app) + .post("/issues/i-1/interactions/x-1/reject") + .set("x-test-companies", "company-1,company-2") + .expect(200); + await shutdownTelemetry(); + + const routines = posthog.captured.filter((message) => message.event === "routine.created"); + expect(routines[0]!.properties).toMatchObject({ company_id: "company-1", user_id: "user-1" }); + expect(routines[1]!.properties).not.toHaveProperty("company_id"); + }); + + it("Cloud: work that outlives its request does not inherit the request's user", async () => { + const posthog = fakePostHog(); + initTelemetry({ enabled: true }, { env: CLOUD_ENV, postHogFactory: posthog.factory }); + const app = express(); + app.use(postHogRequestContextMiddlewareForEnv(CLOUD_ENV)!); + let later: Promise | null = null; + app.post("/start", (req, res) => { + req.actor = { type: "board", userId: "user-1", source: "session" }; + later = new Promise((resolve) => { + res.on("finish", () => + setTimeout(() => { + trackRoutineCreated(getTelemetryClient()!); + resolve(); + }, 5), + ); + }); + res.json({}); + }); + await request(app).post("/start").set("X-POSTHOG-SESSION-ID", "sess-1").expect(200); + await later; + await shutdownTelemetry(); + + const routine = posthog.captured.find((message) => message.event === "routine.created")!; + expect(routine.distinctId).toBe("workspace:stack-123"); + expect(routine.properties).not.toHaveProperty("$session_id"); + }); +}); diff --git a/server/src/__tests__/posthog-direct-transport.test.ts b/server/src/__tests__/posthog-direct-transport.test.ts new file mode 100644 index 00000000000..e38e3958835 --- /dev/null +++ b/server/src/__tests__/posthog-direct-transport.test.ts @@ -0,0 +1,73 @@ +import { describe, expect, it, vi } from "vitest"; +import { createPostHogDirectTransport, type PostHogNodeClient } from "../services/posthog-direct/transport.js"; +import type { CloudPostHogConfig } from "../services/cloud-posthog-config.js"; + +const config: CloudPostHogConfig = { + token: "phc_test", + host: "http://127.0.0.1:1", + environment: "staging", + stackId: "stack-123", + directEnabled: true, + browserEnabled: false, + replayEnabled: false, +}; + +const startup = { + stackSlug: "acme", + primaryHost: "acme.paperclip.app", + app: "paperclip", + schemaVersion: "1", + version: "1.0.0", + installId: "install-1", + installHash: "hash-1", +}; + +function fakeClient() { + const captured: string[] = []; + const groups: string[] = []; + const client: PostHogNodeClient = { + capture: (message) => void captured.push(message.event), + groupIdentify: (message) => void groups.push(message.groupKey), + flush: async () => {}, + shutdown: async () => {}, + }; + return { client, captured, groups }; +} + +describe("PostHog direct transport", () => { + it("re-sends the startup announcement with the first batch after the client failed to load", async () => { + const fake = fakeClient(); + const factory = vi + .fn<() => Promise>() + .mockRejectedValueOnce(new Error("import failed")) + .mockResolvedValue(fake.client); + const transport = createPostHogDirectTransport(config, { factory }); + + await expect(transport.announceWorkspace(startup)).rejects.toThrow("import failed"); + expect(fake.captured).toEqual([]); + + const result = await transport.send({ + app: "paperclip", + schemaVersion: "1", + installId: "install-1", + version: "1.0.0", + batchId: "batch-1", + events: [{ event: { name: "routine.created", occurredAt: "2026-11-17T12:00:00.000Z", dimensions: {} }, context: undefined }], + }); + + expect(result).toEqual({ kind: "ok" }); + expect(fake.groups).toEqual(["stack-123"]); + expect(fake.captured).toEqual(["cloud.workspace_started", "routine.created"]); + + // Sent once only. + await transport.send({ + app: "paperclip", + schemaVersion: "1", + installId: "install-1", + version: "1.0.0", + batchId: "batch-2", + events: [{ event: { name: "routine.created", occurredAt: "2026-11-17T12:00:01.000Z", dimensions: {} }, context: undefined }], + }); + expect(fake.captured.filter((event) => event === "cloud.workspace_started")).toHaveLength(1); + }); +}); diff --git a/server/src/app.ts b/server/src/app.ts index 825a245bfdd..b2b121a7830 100644 --- a/server/src/app.ts +++ b/server/src/app.ts @@ -263,6 +263,7 @@ import { stopServerMetrics, } from "./services/server-metrics.js"; import { chatWebhookBodyParser } from "./middleware/chat-webhook-body.js"; +import { postHogRequestContextMiddlewareForEnv } from "./services/posthog-direct/request-context.js"; import { createChatWebhookDiagnostics } from "./services/chat-webhook-diagnostics.js"; type UiMode = "none" | "static" | "vite-dev"; @@ -557,6 +558,11 @@ export async function createApp( app.use((req, res, next) => (dotPrincipalHttp.matchesPost(req) || ["/mcp/files/upload", "/mcp/runner/files/upload"].includes(req.path)) ? next() : jsonBodyParser(req, res, next)); app.use("/api", apiCompression()); app.use(httpLogger); + // Paperclip Cloud only: link server analytics events to the browser session + // that caused them. Self-hosted servers never mount this, so posthog-js + // tracing headers are ignored there. + const postHogRequestContext = postHogRequestContextMiddlewareForEnv(); + if (postHogRequestContext) app.use(postHogRequestContext); const privateHostnameGateEnabled = shouldEnablePrivateHostnameGuard({ deploymentMode: opts.deploymentMode, deploymentExposure: opts.deploymentExposure, diff --git a/server/src/index.ts b/server/src/index.ts index 0fb6d43c6d4..4efa6af8612 100644 --- a/server/src/index.ts +++ b/server/src/index.ts @@ -212,7 +212,7 @@ import { abortInFlightMultipartUploads } from "./storage/s3-multipart.js"; import { printStartupBanner } from "./startup-banner.js"; import { getBoardClaimWarningUrl, initializeBoardClaimChallenge } from "./board-claim.js"; import { maybePersistWorktreeRuntimePorts } from "./worktree-config.js"; -import { initTelemetry, getTelemetryClient } from "./telemetry.js"; +import { initTelemetry, getTelemetryClient, shutdownTelemetry } from "./telemetry.js"; import { conflict } from "./errors.js"; import { ensureDecisionSigningSecret } from "./services/decision-signing.js"; import { createDecisionRetentionNotifyOriginAgent, createDecisionWakeOriginAgent } from "./services/decision-wakeup.js"; @@ -2361,14 +2361,13 @@ async function startServerWithDatabaseTeardown( }); } - const telemetryClient = getTelemetryClient(); - if (telemetryClient) { - telemetryClient.stop(); + if (getTelemetryClient()) { await runBoundedShutdownStep({ step: "telemetry_flush", signal, timeoutMs: 5_000, - run: () => telemetryClient.flush(), + // Flushes queued events, then closes the Cloud PostHog client if any. + run: () => shutdownTelemetry(), log: logger, }); } diff --git a/server/src/services/cloud-posthog-config.ts b/server/src/services/cloud-posthog-config.ts new file mode 100644 index 00000000000..083dae61fbe --- /dev/null +++ b/server/src/services/cloud-posthog-config.ts @@ -0,0 +1,54 @@ +import { isCloudManagedInstance, type CloudInstanceEnv } from "./cloud-instance.js"; + +/** + * PostHog settings for a Paperclip Cloud stack. Present only on a + * Cloud-managed instance that has a project token and a stack id; every + * self-hosted install resolves `null` and keeps the collector path. + */ +export type CloudPostHogConfig = { + token: string; // PAPERCLIP_POSTHOG_PROJECT_TOKEN + host: string; // PAPERCLIP_POSTHOG_HOST, default "https://us.i.posthog.com" + environment: string | null; // PAPERCLIP_POSTHOG_ENVIRONMENT + stackId: string; // PAPERCLIP_CLOUD_STACK_ID + directEnabled: boolean; // PAPERCLIP_POSTHOG_DIRECT !== "0" + browserEnabled: boolean; // PAPERCLIP_POSTHOG_BROWSER_ENABLED === "1" + replayEnabled: boolean; // browserEnabled && PAPERCLIP_POSTHOG_REPLAY_ENABLED !== "0" +}; + +export const DEFAULT_CLOUD_POSTHOG_HOST = "https://us.i.posthog.com"; + +function readEnv(env: CloudInstanceEnv, name: string): string | null { + const value = env[name]?.trim(); + return value ? value : null; +} + +export function resolveCloudPostHogConfig( + env: Record = process.env, +): CloudPostHogConfig | null { + if (!isCloudManagedInstance(env)) return null; + const token = readEnv(env, "PAPERCLIP_POSTHOG_PROJECT_TOKEN"); + const stackId = readEnv(env, "PAPERCLIP_CLOUD_STACK_ID"); + if (!token || !stackId) return null; + + const browserEnabled = readEnv(env, "PAPERCLIP_POSTHOG_BROWSER_ENABLED") === "1"; + return { + token, + host: (readEnv(env, "PAPERCLIP_POSTHOG_HOST") ?? DEFAULT_CLOUD_POSTHOG_HOST).replace(/\/+$/, ""), + environment: readEnv(env, "PAPERCLIP_POSTHOG_ENVIRONMENT"), + stackId, + directEnabled: readEnv(env, "PAPERCLIP_POSTHOG_DIRECT") !== "0", + browserEnabled, + replayEnabled: browserEnabled && readEnv(env, "PAPERCLIP_POSTHOG_REPLAY_ENABLED") !== "0", + }; +} + +/** + * Whether server events go straight to PostHog. Requires the kill switch to + * be on and an environment: every direct event carries `environment`, so + * without one the stack keeps using the collector. + */ +export function isPostHogDirectDeliveryEnabled( + config: CloudPostHogConfig | null, +): config is CloudPostHogConfig & { environment: string } { + return Boolean(config?.directEnabled && config.environment); +} diff --git a/server/src/services/posthog-direct/__fixtures__/loader-golden.json b/server/src/services/posthog-direct/__fixtures__/loader-golden.json new file mode 100644 index 00000000000..9e7a85841e9 --- /dev/null +++ b/server/src/services/posthog-direct/__fixtures__/loader-golden.json @@ -0,0 +1,424 @@ +{ + "ingestedAt": "2026-11-17T12:00:00.000Z", + "rawTaskId": "6f1f3c2a-9b8e-4d7c-a1b2-c3d4e5f60718", + "hashedTaskId": "9c1e5b7a3d2f4e60", + "envelope": { + "app": "paperclip", + "schemaVersion": "1", + "installId": "11111111-2222-4333-8444-555555555555", + "version": "2026.1117.0", + "batchId": "fixture-batch-0001", + "events": [ + { + "name": "server.started", + "occurredAt": "2026-11-17T11:58:00.000Z", + "dimensions": { + "os_platform": "linux" + } + }, + { + "name": "agent.task_run", + "occurredAt": "2026-11-17T11:58:01.000Z", + "dimensions": { + "agent_id": "2f6c7d1e-0a4b-4c3d-9e8f-112233445566", + "state": "succeeded", + "adapter_type": "claude_local", + "agent_role": "engineer", + "model": "claude-opus-5-5", + "duration_seconds": 42, + "input_tokens": 1200, + "output_tokens": 300, + "task_id": "9c1e5b7a3d2f4e60" + } + }, + { + "name": "agent.created", + "occurredAt": "2026-11-17T11:58:02.000Z", + "dimensions": { + "agent_id": "3a7b8c9d-1e2f-4a5b-8c6d-778899aabbcc", + "agent_role": "astronaut" + } + }, + { + "name": "install.completed", + "occurredAt": "2026-11-17T11:58:03.000Z", + "dimensions": { + "adapter_type": "future_adapter" + } + }, + { + "name": "skill.imported", + "occurredAt": "2026-11-17T11:58:04.000Z", + "dimensions": { + "source_type": "mystery_source" + } + }, + { + "name": "interaction.resolved", + "occurredAt": "2026-11-17T11:58:05.000Z", + "dimensions": { + "interaction_kind": "suggest_tasks", + "status": "accepted", + "resolved_by_kind": "user", + "option_count": 3, + "selected_option_count": 2, + "legacy_inherited_restriction": false + } + }, + { + "name": "routine.created", + "occurredAt": "2026-11-17T11:58:06.000Z", + "dimensions": {} + }, + { + "name": "question_response.delivery", + "occurredAt": "2026-11-17T11:58:07.000Z", + "dimensions": { + "outcome": "delivered" + } + } + ] + }, + "canonicalRecords": [ + { + "source": "client", + "event_id": "a77f7fdef12def432e98412718b080efc3db2b4c0735bbbd623f7051dc4e6e76", + "app": "paperclip", + "schema_version": "1", + "version": "2026.1117.0", + "envelope_version": 2, + "app_version": "2026.1117.0", + "event_name": "server.started", + "occurred_at": "2026-11-17T11:58:00.000Z", + "ingested_at": "2026-11-17T12:00:00.000Z", + "install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49", + "dimensions": { + "os_platform": "linux" + }, + "normalized_properties": [], + "backfilled": false, + "deployment_source": "cloud", + "event_date": "2026-11-17", + "hour": "11" + }, + { + "source": "client", + "event_id": "a4d9c57bc5d720ce3c7c25cf145499eb98e62639f782a545fd360717cdc8c635", + "app": "paperclip", + "schema_version": "1", + "version": "2026.1117.0", + "envelope_version": 2, + "app_version": "2026.1117.0", + "event_name": "agent.task_run", + "occurred_at": "2026-11-17T11:58:01.000Z", + "ingested_at": "2026-11-17T12:00:00.000Z", + "install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49", + "dimensions": { + "agent_id": "282a1c1fae5df6996043f35138b162af4e794c00cf68087665b1a39c8b4980ca", + "state": "succeeded", + "adapter_type": "claude_local", + "agent_role": "engineer", + "model": "claude-opus-5-5", + "duration_seconds": 42, + "input_tokens": 1200, + "output_tokens": 300, + "task_id": "9c1e5b7a3d2f4e60" + }, + "normalized_properties": [], + "backfilled": false, + "deployment_source": "cloud", + "event_date": "2026-11-17", + "hour": "11" + }, + { + "source": "client", + "event_id": "22fae133df11fcfd31fe83847aa7206f90c4254a54b1a924c589ad4cec119846", + "app": "paperclip", + "schema_version": "1", + "version": "2026.1117.0", + "envelope_version": 2, + "app_version": "2026.1117.0", + "event_name": "agent.created", + "occurred_at": "2026-11-17T11:58:02.000Z", + "ingested_at": "2026-11-17T12:00:00.000Z", + "install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49", + "dimensions": { + "agent_id": "9532a2b6bf43a010107bb5c09020418d34165f50155dfba097c49ae53269afb0", + "agent_role": "other" + }, + "normalized_properties": [ + "agent_role" + ], + "backfilled": false, + "deployment_source": "cloud", + "event_date": "2026-11-17", + "hour": "11" + }, + { + "source": "client", + "event_id": "f66fe4effe5ef14500271e97791576ade468152b3e6b15e56dfc2c9deaa4333b", + "app": "paperclip", + "schema_version": "1", + "version": "2026.1117.0", + "envelope_version": 2, + "app_version": "2026.1117.0", + "event_name": "install.completed", + "occurred_at": "2026-11-17T11:58:03.000Z", + "ingested_at": "2026-11-17T12:00:00.000Z", + "install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49", + "dimensions": { + "adapter_type": "other" + }, + "normalized_properties": [ + "adapter_type" + ], + "backfilled": false, + "deployment_source": "cloud", + "event_date": "2026-11-17", + "hour": "11" + }, + { + "source": "client", + "event_id": "ec19908cf8c99d58357929b2ee9c494ba3af8f04a5ade3e26eeac1188bc2560c", + "app": "paperclip", + "schema_version": "1", + "version": "2026.1117.0", + "envelope_version": 2, + "app_version": "2026.1117.0", + "event_name": "skill.imported", + "occurred_at": "2026-11-17T11:58:04.000Z", + "ingested_at": "2026-11-17T12:00:00.000Z", + "install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49", + "dimensions": { + "source_type": "unknown" + }, + "normalized_properties": [ + "source_type" + ], + "backfilled": false, + "deployment_source": "cloud", + "event_date": "2026-11-17", + "hour": "11" + }, + { + "source": "client", + "event_id": "2d7c541d00ca3b5971d56d8cf43f02d79e1bbae41fc526b1490c4640a627e2fe", + "app": "paperclip", + "schema_version": "1", + "version": "2026.1117.0", + "envelope_version": 2, + "app_version": "2026.1117.0", + "event_name": "interaction.resolved", + "occurred_at": "2026-11-17T11:58:05.000Z", + "ingested_at": "2026-11-17T12:00:00.000Z", + "install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49", + "dimensions": { + "interaction_kind": "suggest_tasks", + "status": "accepted", + "resolved_by_kind": "user", + "option_count": 3, + "selected_option_count": 2, + "legacy_inherited_restriction": false + }, + "normalized_properties": [], + "backfilled": false, + "deployment_source": "cloud", + "event_date": "2026-11-17", + "hour": "11" + }, + { + "source": "client", + "event_id": "369e2de4dbd5da7871377958422888401120642e2b0edafa3f3002e58f1d6fe9", + "app": "paperclip", + "schema_version": "1", + "version": "2026.1117.0", + "envelope_version": 2, + "app_version": "2026.1117.0", + "event_name": "routine.created", + "occurred_at": "2026-11-17T11:58:06.000Z", + "ingested_at": "2026-11-17T12:00:00.000Z", + "install_id": "cf4c4732fd3b8f8a55b60871950a2f22c893ea7afd75d2146826534e3f67cc49", + "dimensions": {}, + "normalized_properties": [], + "backfilled": false, + "deployment_source": "cloud", + "event_date": "2026-11-17", + "hour": "11" + } + ], + "loaderEvents": [ + { + "event": "server.started", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "timestamp": "2026-11-17T11:58:00.000Z", + "uuid": "a77f7fde-f12d-4f43-ae98-412718b080ef", + "disableGeoip": true, + "sendFeatureFlags": false, + "properties": { + "app": "paperclip", + "schema_version": "1", + "source": "client", + "deployment_source": "cloud", + "ingested_at": "2026-11-17T12:00:00.000Z", + "event_date": "2026-11-17", + "hour": "11", + "normalized_properties": [], + "version": "2026.1117.0", + "os_platform": "linux", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "$process_person_profile": false + } + }, + { + "event": "agent.task_run", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "timestamp": "2026-11-17T11:58:01.000Z", + "uuid": "a4d9c57b-c5d7-40ce-bc7c-25cf145499eb", + "disableGeoip": true, + "sendFeatureFlags": false, + "properties": { + "app": "paperclip", + "schema_version": "1", + "source": "client", + "deployment_source": "cloud", + "ingested_at": "2026-11-17T12:00:00.000Z", + "event_date": "2026-11-17", + "hour": "11", + "normalized_properties": [], + "version": "2026.1117.0", + "agent_id": "282a1c1fae5df6996043f35138b162af4e794c00cf68087665b1a39c8b4980ca", + "state": "succeeded", + "adapter_type": "claude_local", + "agent_role": "engineer", + "model": "claude-opus-5-5", + "duration_seconds": 42, + "input_tokens": 1200, + "output_tokens": 300, + "task_id": "9c1e5b7a3d2f4e60", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "$process_person_profile": false + } + }, + { + "event": "agent.created", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "timestamp": "2026-11-17T11:58:02.000Z", + "uuid": "22fae133-df11-4cfd-b1fe-83847aa7206f", + "disableGeoip": true, + "sendFeatureFlags": false, + "properties": { + "app": "paperclip", + "schema_version": "1", + "source": "client", + "deployment_source": "cloud", + "ingested_at": "2026-11-17T12:00:00.000Z", + "event_date": "2026-11-17", + "hour": "11", + "normalized_properties": [ + "agent_role" + ], + "version": "2026.1117.0", + "agent_id": "9532a2b6bf43a010107bb5c09020418d34165f50155dfba097c49ae53269afb0", + "agent_role": "other", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "$process_person_profile": false + } + }, + { + "event": "install.completed", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "timestamp": "2026-11-17T11:58:03.000Z", + "uuid": "f66fe4ef-fe5e-4145-8027-1e97791576ad", + "disableGeoip": true, + "sendFeatureFlags": false, + "properties": { + "app": "paperclip", + "schema_version": "1", + "source": "client", + "deployment_source": "cloud", + "ingested_at": "2026-11-17T12:00:00.000Z", + "event_date": "2026-11-17", + "hour": "11", + "normalized_properties": [ + "adapter_type" + ], + "version": "2026.1117.0", + "adapter_type": "other", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "$process_person_profile": false + } + }, + { + "event": "skill.imported", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "timestamp": "2026-11-17T11:58:04.000Z", + "uuid": "ec19908c-f8c9-4d58-b579-29b2ee9c494b", + "disableGeoip": true, + "sendFeatureFlags": false, + "properties": { + "app": "paperclip", + "schema_version": "1", + "source": "client", + "deployment_source": "cloud", + "ingested_at": "2026-11-17T12:00:00.000Z", + "event_date": "2026-11-17", + "hour": "11", + "normalized_properties": [ + "source_type" + ], + "version": "2026.1117.0", + "source_type": "unknown", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "$process_person_profile": false + } + }, + { + "event": "interaction.resolved", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "timestamp": "2026-11-17T11:58:05.000Z", + "uuid": "2d7c541d-00ca-4b59-b1d5-6d8cf43f02d7", + "disableGeoip": true, + "sendFeatureFlags": false, + "properties": { + "app": "paperclip", + "schema_version": "1", + "source": "client", + "deployment_source": "cloud", + "ingested_at": "2026-11-17T12:00:00.000Z", + "event_date": "2026-11-17", + "hour": "11", + "normalized_properties": [], + "version": "2026.1117.0", + "interaction_kind": "suggest_tasks", + "status": "accepted", + "resolved_by_kind": "user", + "option_count": 3, + "selected_option_count": 2, + "legacy_inherited_restriction": false, + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "$process_person_profile": false + } + }, + { + "event": "routine.created", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "timestamp": "2026-11-17T11:58:06.000Z", + "uuid": "369e2de4-dbd5-4a78-b137-795842288840", + "disableGeoip": true, + "sendFeatureFlags": false, + "properties": { + "app": "paperclip", + "schema_version": "1", + "source": "client", + "deployment_source": "cloud", + "ingested_at": "2026-11-17T12:00:00.000Z", + "event_date": "2026-11-17", + "hour": "11", + "normalized_properties": [], + "version": "2026.1117.0", + "distinct_id": "5564e194c3d2f9a37a7e3c1443f5abfaf922f4c4ee8de2b821eb1491b36d19fb", + "$process_person_profile": false + } + } + ] +} diff --git a/server/src/services/posthog-direct/enum-fallbacks.generated.ts b/server/src/services/posthog-direct/enum-fallbacks.generated.ts new file mode 100644 index 00000000000..1a67f5e5fc1 --- /dev/null +++ b/server/src/services/posthog-direct/enum-fallbacks.generated.ts @@ -0,0 +1,118 @@ +// GENERATED by scripts/generate-posthog-direct-fixtures.mjs from the telemetry +// backend's event manifest (x-normalize.unknown_enum_value). DO NOT EDIT. +// Enum domains come from PAPERCLIP_ENUM_DESCRIPTIONS in @paperclipai/shared. + +export const UNKNOWN_ENUM_FALLBACKS = { + "agent.created": { + "agent_role": { + "fallback": "other", + "required": true + } + }, + "agent.first_heartbeat": { + "agent_role": { + "fallback": "other", + "required": true + } + }, + "agent.task_completed": { + "adapter_type": { + "fallback": "other", + "required": true + }, + "agent_role": { + "fallback": "other", + "required": true + } + }, + "agent.task_run": { + "adapter_type": { + "fallback": "other", + "required": false + }, + "agent_role": { + "fallback": "other", + "required": false + } + }, + "company.imported": { + "source_type": { + "fallback": "unknown", + "required": true + } + }, + "goal.created": { + "goal_level": { + "fallback": "other", + "required": true + } + }, + "install.completed": { + "adapter_type": { + "fallback": "other", + "required": true + } + }, + "interaction.created": { + "interaction_kind": { + "fallback": "other", + "required": true + } + }, + "interaction.resolved": { + "interaction_kind": { + "fallback": "other", + "required": true + }, + "status": { + "fallback": "other", + "required": true + }, + "resolution_reason": { + "fallback": "other", + "required": false + }, + "resolved_by_kind": { + "fallback": "other", + "required": true + }, + "created_by_kind": { + "fallback": "other", + "required": false + }, + "creator_agent_role": { + "fallback": "other", + "required": false + }, + "continuation_policy": { + "fallback": "other", + "required": false + }, + "target_type": { + "fallback": "other", + "required": false + } + }, + "routine.run": { + "source": { + "fallback": "other", + "required": true + }, + "status": { + "fallback": "other", + "required": true + } + }, + "server.started": { + "os_platform": { + "fallback": "other", + "required": true + } + }, + "skill.imported": { + "source_type": { + "fallback": "unknown", + "required": true + } + } +} as const; diff --git a/server/src/services/posthog-direct/event-shape.ts b/server/src/services/posthog-direct/event-shape.ts new file mode 100644 index 00000000000..7b763028cb6 --- /dev/null +++ b/server/src/services/posthog-direct/event-shape.ts @@ -0,0 +1,233 @@ +import { createHash } from "node:crypto"; +import { + PAPERCLIP_ENUM_DESCRIPTIONS, + PAPERCLIP_EVENTS, + type TelemetryDimensions, + type TelemetryEvent, +} from "@paperclipai/shared/telemetry"; +import type { CloudPostHogConfig } from "../cloud-posthog-config.js"; +import { UNKNOWN_ENUM_FALLBACKS } from "./enum-fallbacks.generated.js"; +import type { PostHogEventContext } from "./request-context.js"; + +/** + * Builds PostHog capture messages for Paperclip Cloud direct delivery. + * + * The shape mirrors what the telemetry backend produces today for collector + * events (ingest `normalizeCanonicalRecord` + loader `buildPostHogEvent`), so + * existing insights keep working: same event names, metadata keys, + * deterministic uuid, and enum fallback normalization. The intended Cloud + * differences are real identifiers (distinct_id, agent_id, private refs) and + * the added workspace properties (stack_id, company_id, user_id, environment, + * $groups, $session_id, $window_id). + */ + +export const POSTHOG_WORKSPACE_GROUP_TYPE = "workspace"; + +/** + * Direct-path-only startup event. It is not in the generated contract and + * never goes through the collector. It carries the hashed install id so an + * offline job can join pre-switch history to the workspace without group + * analytics. + */ +export const CLOUD_WORKSPACE_STARTED_EVENT = "cloud.workspace_started"; + +export type PostHogDirectEvent = { + event: string; + distinct_id: string; + timestamp: string; + uuid: string; + disableGeoip: true; + sendFeatureFlags: false; + properties: Record; +}; + +export type PostHogDirectBatchMeta = { + app: string; + schemaVersion: string; + installId: string; + version: string; + ingestedAt: string; +}; + +type IdentityConfig = Pick; + +function stableJson(value: unknown): string { + if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`; + if (value && typeof value === "object") { + const record = value as Record; + return `{${Object.keys(record) + .sort() + .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`) + .join(",")}}`; + } + return JSON.stringify(value); +} + +/** Same formula as the telemetry backend's `deterministicEventId`. */ +export function deterministicEventId(input: { + app: string; + installId: string; + event: { name: string; occurredAt: string; dimensions: TelemetryDimensions }; +}): string { + return createHash("sha256") + .update(String(input.app)) + .update("\0") + .update(String(input.installId)) + .update("\0") + .update(String(input.event.name)) + .update("\0") + .update(String(input.event.occurredAt)) + .update("\0") + .update(stableJson(input.event.dimensions ?? {})) + .digest("hex"); +} + +/** Same formula as the telemetry backend's `eventIdToPostHogUuid`. */ +export function eventIdToPostHogUuid(eventId: string): string { + if (!/^[0-9a-f]{64}$/.test(eventId)) { + throw new Error("eventIdToPostHogUuid requires a 64 lowercase hex event id"); + } + const chars = eventId.slice(0, 32).split(""); + chars[12] = "4"; + chars[16] = ((parseInt(chars[16]!, 16) & 0x3) | 0x8).toString(16); + const hex = chars.join(""); + return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`; +} + +const ENUM_DOMAINS = PAPERCLIP_ENUM_DESCRIPTIONS as Record>>; +const FALLBACKS = UNKNOWN_ENUM_FALLBACKS as Record>; + +/** + * Applies the backend's unknown-enum fallback. Returns null for an event the + * collector path would quarantine (and so never reach PostHog): an + * unregistered name, or an unknown enum value whose fallback is itself not an + * allowed value. + */ +export function normalizeDimensions( + eventName: string, + dimensions: TelemetryDimensions, +): { dimensions: TelemetryDimensions; normalizedProperties: string[] } | null { + if (!Object.hasOwn(PAPERCLIP_EVENTS, eventName)) return null; + const normalized: TelemetryDimensions = { ...dimensions }; + const normalizedProperties: string[] = []; + for (const [key, rule] of Object.entries(FALLBACKS[eventName] ?? {})) { + const allowed = Object.keys(ENUM_DOMAINS[eventName]?.[key] ?? {}); + const value = normalized[key]; + if (value === undefined) { + if (rule.required && allowed.includes(rule.fallback)) { + normalized[key] = rule.fallback; + normalizedProperties.push(key); + } + continue; + } + if (allowed.length > 0 && !allowed.includes(String(value))) { + if (!allowed.includes(rule.fallback)) return null; + normalized[key] = rule.fallback; + normalizedProperties.push(key); + } + } + return { dimensions: normalized, normalizedProperties: normalizedProperties.sort() }; +} + +function utcPartitions(occurredAt: string): { event_date: string; hour: string } { + const ts = new Date(occurredAt); + return { + event_date: ts.toISOString().slice(0, 10), + hour: String(ts.getUTCHours()).padStart(2, "0"), + }; +} + +/** The acting user when known, else the workspace. */ +export function resolveDistinctId(config: IdentityConfig, context: PostHogEventContext | undefined): string { + return context?.userId ?? `workspace:${config.stackId}`; +} + +export function buildPostHogDirectEvent( + event: TelemetryEvent, + context: PostHogEventContext | undefined, + meta: PostHogDirectBatchMeta, + config: IdentityConfig, +): PostHogDirectEvent | null { + const normalized = normalizeDimensions(event.name, event.dimensions ?? {}); + if (!normalized) return null; + const eventId = deterministicEventId({ + app: meta.app, + installId: meta.installId, + event: { name: event.name, occurredAt: event.occurredAt, dimensions: normalized.dimensions }, + }); + const distinctId = resolveDistinctId(config, context); + const hasPerson = Boolean(context?.userId); + return { + event: event.name, + distinct_id: distinctId, + timestamp: event.occurredAt, + uuid: eventIdToPostHogUuid(eventId), + disableGeoip: true, + sendFeatureFlags: false, + properties: { + // Metadata keys and order match the backend loader's buildProperties(). + app: meta.app, + schema_version: meta.schemaVersion, + source: "client", + deployment_source: "cloud", + ingested_at: meta.ingestedAt, + ...utcPartitions(event.occurredAt), + normalized_properties: normalized.normalizedProperties, + ...(meta.version ? { version: meta.version } : {}), + ...normalized.dimensions, + // Cloud-only properties. + stack_id: config.stackId, + ...(context?.companyId ? { company_id: context.companyId } : {}), + ...(context?.userId ? { user_id: context.userId } : {}), + ...(config.environment ? { environment: config.environment } : {}), + ...(context?.sessionId ? { $session_id: context.sessionId } : {}), + ...(context?.windowId ? { $window_id: context.windowId } : {}), + $groups: { [POSTHOG_WORKSPACE_GROUP_TYPE]: config.stackId }, + distinct_id: distinctId, + // A workspace id must never become a person profile. + ...(hasPerson ? {} : { $process_person_profile: false }), + }, + }; +} + +/** The `cloud.workspace_started` event sent once per server start on Cloud. */ +export function buildWorkspaceStartedEvent( + input: { installHash: string; occurredAt: string }, + meta: PostHogDirectBatchMeta, + config: IdentityConfig, +): PostHogDirectEvent { + const distinctId = resolveDistinctId(config, undefined); + const eventId = deterministicEventId({ + app: meta.app, + installId: meta.installId, + event: { + name: CLOUD_WORKSPACE_STARTED_EVENT, + occurredAt: input.occurredAt, + dimensions: { stack_id: config.stackId, install_hash: input.installHash }, + }, + }); + return { + event: CLOUD_WORKSPACE_STARTED_EVENT, + distinct_id: distinctId, + timestamp: input.occurredAt, + uuid: eventIdToPostHogUuid(eventId), + disableGeoip: true, + sendFeatureFlags: false, + properties: { + app: meta.app, + schema_version: meta.schemaVersion, + source: "client", + deployment_source: "cloud", + ingested_at: meta.ingestedAt, + ...utcPartitions(input.occurredAt), + normalized_properties: [], + ...(meta.version ? { version: meta.version } : {}), + stack_id: config.stackId, + install_hash: input.installHash, + ...(config.environment ? { environment: config.environment } : {}), + $groups: { [POSTHOG_WORKSPACE_GROUP_TYPE]: config.stackId }, + distinct_id: distinctId, + $process_person_profile: false, + }, + }; +} diff --git a/server/src/services/posthog-direct/index.ts b/server/src/services/posthog-direct/index.ts new file mode 100644 index 00000000000..fc5ef37cd54 --- /dev/null +++ b/server/src/services/posthog-direct/index.ts @@ -0,0 +1,13 @@ +export { + createPostHogDirectTransport, + loadPostHogNode, + type PostHogDirectTransport, + type PostHogNodeClient, + type PostHogNodeFactory, +} from "./transport.js"; +export { + capturePostHogEventContext, + postHogRequestContextMiddleware, + type PostHogEventContext, +} from "./request-context.js"; +export { buildPostHogDirectEvent, type PostHogDirectEvent } from "./event-shape.js"; diff --git a/server/src/services/posthog-direct/request-context.ts b/server/src/services/posthog-direct/request-context.ts new file mode 100644 index 00000000000..6c1b3dbc2d8 --- /dev/null +++ b/server/src/services/posthog-direct/request-context.ts @@ -0,0 +1,110 @@ +import { AsyncLocalStorage } from "node:async_hooks"; +import type { Request, RequestHandler } from "express"; +import { isPostHogDirectDeliveryEnabled, resolveCloudPostHogConfig } from "../cloud-posthog-config.js"; + +/** + * Request-scoped analytics context for Paperclip Cloud direct delivery. + * + * The store holds the live request so the acting user is read from the + * authenticated actor when an event is tracked, whichever middleware set it. + * The posthog-js tracing headers only link an event to a browser session and + * window. They never identify a person and never authorize anything. + */ +type PostHogRequestStore = { + req: Request; + sessionId: string | null; + windowId: string | null; + // False once the response finishes. Work that outlives its request (timers, + // background loops started during the request) must not keep attributing + // events to that request's user or session. + active: boolean; +}; + +export type PostHogEventContext = { + userId?: string; + companyId?: string; + sessionId?: string; + windowId?: string; +}; + +export const POSTHOG_SESSION_ID_HEADER = "x-posthog-session-id"; +export const POSTHOG_WINDOW_ID_HEADER = "x-posthog-window-id"; + +const storage = new AsyncLocalStorage(); +const TRACING_ID_RE = /^[A-Za-z0-9-]{1,64}$/; + +function readTracingHeader(req: Request, name: string): string | null { + const value = req.headers[name]; + const raw = Array.isArray(value) ? value[0] : value; + const trimmed = raw?.trim(); + return trimmed && TRACING_ID_RE.test(trimmed) ? trimmed : null; +} + +/** + * Express middleware that opens the request-scoped context. Mount it only on + * a Cloud stack with direct delivery on; self-hosted servers never mount it, + * so their requests carry no session context and the headers are ignored. + */ +export function postHogRequestContextMiddleware(): RequestHandler { + return (req, res, next) => { + const store: PostHogRequestStore = { + req, + sessionId: readTracingHeader(req, POSTHOG_SESSION_ID_HEADER), + windowId: readTracingHeader(req, POSTHOG_WINDOW_ID_HEADER), + active: true, + }; + const end = () => { + store.active = false; + }; + res.once("finish", end); + res.once("close", end); + storage.run(store, next); + }; +} + +/** + * The request-context middleware for this process, or null when direct + * delivery is off (every self-hosted install, a Cloud stack without a token + * or environment, or the PAPERCLIP_POSTHOG_DIRECT=0 kill switch). + */ +export function postHogRequestContextMiddlewareForEnv( + env: Record = process.env, +): RequestHandler | null { + return isPostHogDirectDeliveryEnabled(resolveCloudPostHogConfig(env)) ? postHogRequestContextMiddleware() : null; +} + +function actingUserId(req: Request): string | undefined { + const actor = req.actor; + if (!actor || actor.type !== "board" || !actor.userId) return undefined; + // Local implicit and Cloud control actors are not a signed-in person. + if (actor.source === "local_implicit" || actor.source === "cloud_control") return undefined; + return actor.userId; +} + +/** + * The company the request acts in, when the request itself says so: an agent + * actor's company, the route's `:companyId`, or else the board actor's only + * company (a Cloud stack usually has one). A board user with several companies + * on a route without `:companyId` has no known company. + */ +function knownCompanyId(req: Request): string | undefined { + if (req.actor?.companyId) return req.actor.companyId; + const fromParams = (req.params as Record | undefined)?.companyId; + if (typeof fromParams === "string" && fromParams) return fromParams; + const companyIds = req.actor?.companyIds; + return companyIds?.length === 1 ? companyIds[0] : undefined; +} + +/** Snapshot of the current request's analytics context, taken at track time. */ +export function capturePostHogEventContext(): PostHogEventContext | undefined { + const store = storage.getStore(); + if (!store || !store.active) return undefined; + const context: PostHogEventContext = {}; + const userId = actingUserId(store.req); + const companyId = knownCompanyId(store.req); + if (userId) context.userId = userId; + if (companyId) context.companyId = companyId; + if (store.sessionId) context.sessionId = store.sessionId; + if (store.windowId) context.windowId = store.windowId; + return Object.keys(context).length > 0 ? context : undefined; +} diff --git a/server/src/services/posthog-direct/transport.ts b/server/src/services/posthog-direct/transport.ts new file mode 100644 index 00000000000..7f5d974e5b1 --- /dev/null +++ b/server/src/services/posthog-direct/transport.ts @@ -0,0 +1,211 @@ +import type { + TelemetryOutgoingBatch, + TelemetrySendResult, + TelemetryTransport, +} from "@paperclipai/shared/telemetry"; +import type { CloudPostHogConfig } from "../cloud-posthog-config.js"; +import { + buildPostHogDirectEvent, + buildWorkspaceStartedEvent, + POSTHOG_WORKSPACE_GROUP_TYPE, + type PostHogDirectEvent, +} from "./event-shape.js"; +import { capturePostHogEventContext, type PostHogEventContext } from "./request-context.js"; + +const POSTHOG_SHUTDOWN_TIMEOUT_MS = 3_000; + +/** The slice of the posthog-node client this transport uses. */ +export type PostHogNodeClient = { + capture(message: { + distinctId: string; + event: string; + properties?: Record; + timestamp?: Date; + uuid?: string; + groups?: Record; + disableGeoip?: boolean; + sendFeatureFlags?: boolean; + }): void; + groupIdentify(message: { + groupType: string; + groupKey: string; + properties?: Record; + disableGeoip?: boolean; + }): void; + flush(): Promise; + shutdown(shutdownTimeoutMs?: number): Promise | void; +}; + +export type PostHogNodeFactory = (config: CloudPostHogConfig) => Promise; + +/** + * Loads posthog-node only when a Cloud stack actually sends. A self-hosted + * server never reaches this function, so it never loads the package. + */ +export const loadPostHogNode: PostHogNodeFactory = async (config) => { + const { PostHog } = await import("posthog-node"); + return new PostHog(config.token, { + host: config.host, + // The telemetry client already batches; send each flushed batch promptly. + flushAt: 50, + flushInterval: 10_000, + disableGeoip: true, + }) as unknown as PostHogNodeClient; +}; + +export type WorkspaceStartup = { + stackSlug: string | null; + primaryHost: string | null; + app: string; + schemaVersion: string; + version: string; + installId: string; + /** + * sha256 hex of the raw install id: the same canonical install_id the + * telemetry backend computes. Not secret. An offline operator job derives + * the pre-switch PostHog id from it, so history stays joinable. Sent only on + * `cloud.workspace_started`, never on the group or on ordinary events. + */ + installHash: string; +}; + +export type PostHogDirectTransport = TelemetryTransport & { + /** Sends `$groupidentify` and `cloud.workspace_started` for this start. */ + announceWorkspace(startup: WorkspaceStartup): Promise; + shutdown(): Promise; +}; + +export function createPostHogDirectTransport( + config: CloudPostHogConfig, + options: { factory?: PostHogNodeFactory; now?: () => Date } = {}, +): PostHogDirectTransport { + const factory = options.factory ?? loadPostHogNode; + const now = options.now ?? (() => new Date()); + let clientPromise: Promise | null = null; + let pendingAnnouncement: { startup: WorkspaceStartup; occurredAt: string } | null = null; + + const getClient = () => { + clientPromise ??= factory(config).catch((error) => { + clientPromise = null; + throw error; + }); + return clientPromise; + }; + + const capture = (client: PostHogNodeClient, message: PostHogDirectEvent) => { + client.capture({ + distinctId: message.distinct_id, + event: message.event, + properties: message.properties, + timestamp: new Date(message.timestamp), + uuid: message.uuid, + // posthog-node rebuilds `$groups` from this option and drops a `$groups` + // property passed without it. + groups: { [POSTHOG_WORKSPACE_GROUP_TYPE]: config.stackId }, + disableGeoip: message.disableGeoip, + sendFeatureFlags: message.sendFeatureFlags, + }); + }; + + // Group properties need PostHog's group analytics add-on. Send them anyway; + // the history join relies on the plain event below. Both go straight to + // posthog-node: TelemetryClient.track() accepts only generated contract + // events, and these are Cloud-only. + function captureAnnouncement( + client: PostHogNodeClient, + { startup, occurredAt }: { startup: WorkspaceStartup; occurredAt: string }, + ) { + client.groupIdentify({ + groupType: POSTHOG_WORKSPACE_GROUP_TYPE, + groupKey: config.stackId, + disableGeoip: true, + properties: { + stack_slug: startup.stackSlug, + primary_host: startup.primaryHost, + environment: config.environment, + }, + }); + capture( + client, + buildWorkspaceStartedEvent( + { installHash: startup.installHash, occurredAt }, + { + app: startup.app, + schemaVersion: startup.schemaVersion, + installId: startup.installId, + version: startup.version, + ingestedAt: occurredAt, + }, + config, + ), + ); + } + + return { + hashesPrivateRefs: false, + + captureEventContext: () => capturePostHogEventContext(), + + async send(batch: TelemetryOutgoingBatch): Promise { + const meta = { + app: batch.app, + schemaVersion: batch.schemaVersion, + installId: batch.installId, + version: batch.version, + ingestedAt: now().toISOString(), + }; + const messages = batch.events + .map(({ event, context }) => + buildPostHogDirectEvent(event, context as PostHogEventContext | undefined, meta, config), + ) + .filter((message): message is PostHogDirectEvent => message !== null); + if (messages.length === 0) return { kind: "ok" }; + + let client: PostHogNodeClient; + try { + client = await getClient(); + } catch { + // The package could not load. Retrying with backoff is safe: nothing + // was captured yet, so no event can be sent twice. + return { kind: "network" }; + } + // A startup announcement that could not load the client goes out with + // the first batch that can, so the history-join event is not lost. + if (pendingAnnouncement) { + const announcement = pendingAnnouncement; + pendingAnnouncement = null; + captureAnnouncement(client, announcement); + } + for (const message of messages) capture(client, message); + try { + await client.flush(); + } catch { + // posthog-node already retried this request. It keeps events that hit + // a network failure queued for its next flush and drops ones PostHog + // rejected, so resending them from here could only duplicate events. + console.warn(`[telemetry] PostHog flush failed for a batch of ${messages.length} event(s)`); + } + return { kind: "ok" }; + }, + + async announceWorkspace(startup: WorkspaceStartup): Promise { + const announcement = { startup, occurredAt: now().toISOString() }; + let client: PostHogNodeClient; + try { + client = await getClient(); + } catch (error) { + pendingAnnouncement = announcement; + throw error; + } + captureAnnouncement(client, announcement); + await client.flush(); + }, + + async shutdown(): Promise { + if (!clientPromise) return; + const client = await clientPromise.catch(() => null); + if (!client) return; + await client.shutdown(POSTHOG_SHUTDOWN_TIMEOUT_MS); + }, + }; +} diff --git a/server/src/telemetry.ts b/server/src/telemetry.ts index bfa7c1930bb..ec7e49a9993 100644 --- a/server/src/telemetry.ts +++ b/server/src/telemetry.ts @@ -1,17 +1,70 @@ +import { createHash } from "node:crypto"; import path from "node:path"; import { TelemetryClient, + type TelemetryConfig, + type TelemetryState, resolveTelemetryConfig, loadOrCreateState, trackServerStarted, } from "@paperclipai/shared/telemetry"; import { resolvePaperclipInstanceRoot } from "./home-paths.js"; import { serverVersion } from "./version.js"; +import { getCloudStackContext } from "./services/cloud-instance.js"; +import { isPostHogDirectDeliveryEnabled, resolveCloudPostHogConfig } from "./services/cloud-posthog-config.js"; +import { + createPostHogDirectTransport, + type PostHogDirectTransport, + type PostHogNodeFactory, +} from "./services/posthog-direct/index.js"; let client: TelemetryClient | null = null; +let directTransport: PostHogDirectTransport | null = null; let initializationFailed = false; -export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClient | null { +export type InitTelemetryOptions = { + env?: Record; + /** Test seam for the posthog-node client. */ + postHogFactory?: PostHogNodeFactory; +}; + +/** + * Picks the one sender for this process. Self-hosted installs (and Cloud + * stacks without a PostHog token, or with PAPERCLIP_POSTHOG_DIRECT=0) keep the + * collector. A Cloud stack with a token sends every batch straight to PostHog. + */ +function resolveDirectTransport( + options: InitTelemetryOptions, + telemetry: TelemetryConfig, + getState: () => TelemetryState, +): PostHogDirectTransport | null { + const env = options.env ?? process.env; + const config = resolveCloudPostHogConfig(env); + // Every direct event must carry an environment; without one keep the collector. + if (!isPostHogDirectDeliveryEnabled(config)) return null; + const transport = createPostHogDirectTransport(config, { factory: options.postHogFactory }); + const stack = getCloudStackContext(env); + const { installId } = getState(); + void transport + .announceWorkspace({ + stackSlug: stack?.stackSlug ?? null, + primaryHost: stack?.primaryHost ?? null, + app: telemetry.app ?? "paperclip", + schemaVersion: telemetry.schemaVersion ?? "1", + version: serverVersion, + installId, + installHash: createHash("sha256").update(installId).digest("hex"), + }) + .catch(() => { + console.warn("[telemetry] Could not announce the workspace to PostHog."); + }); + return transport; +} + +export function initTelemetry( + fileConfig?: { enabled?: boolean }, + options: InitTelemetryOptions = {}, +): TelemetryClient | null { if (client || initializationFailed) return client; const config = resolveTelemetryConfig(fileConfig); @@ -20,14 +73,20 @@ export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClie let pendingClient: TelemetryClient | null = null; try { const stateDir = path.join(resolvePaperclipInstanceRoot(), "telemetry"); + let state: TelemetryState | null = null; + const getState = () => (state ??= loadOrCreateState(stateDir, serverVersion)); + const transport = resolveDirectTransport(options, config, getState); pendingClient = new TelemetryClient( config, - () => loadOrCreateState(stateDir, serverVersion), + getState, serverVersion, + Math.random, + transport ?? undefined, ); trackServerStarted(pendingClient, { os_platform: process.platform }); pendingClient.startPeriodicFlush(60_000); client = pendingClient; + directTransport = transport; return client; } catch { pendingClient?.stop(); @@ -40,3 +99,28 @@ export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClie export function getTelemetryClient(): TelemetryClient | null { return client; } + +/** Whether this process sends telemetry straight to PostHog (Cloud only). */ +export function isPostHogDirectTelemetryActive(): boolean { + return directTransport !== null; +} + +/** Stops timers, sends queued events, then closes the PostHog client if any. */ +export async function shutdownTelemetry(): Promise { + const current = client; + if (!current) return; + current.stop(); + try { + await current.flush(); + } finally { + await directTransport?.shutdown(); + } +} + +/** Test-only: forget the process-wide client. */ +export function resetTelemetryForTests(): void { + client?.stop(); + client = null; + directTransport = null; + initializationFailed = false; +} diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index 87a681d8392..aa52f0ca8b1 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -351,15 +351,15 @@ "packages/shared/src/slack-tools.ts": "c53a75cd3099c6d8dcd1475e755aae589d4c88f6", "packages/shared/src/subscriptions.ts": "ef70e63395ca967bbc30776b71560e96eb354a75", "packages/shared/src/summary-slot.test.ts": "5f8e222dea425f0d5bff0adb5c683087bd7cf7fb", - "packages/shared/src/telemetry/README.md": "28125b5ab542abc46c4bb6c044636a093f13584f", + "packages/shared/src/telemetry/README.md": "50ae8992b33c4141de443d42c57de24357e3d0aa", "packages/shared/src/telemetry/client-types.test.ts": "3b630edda4972b929ba4decd7457f226eb9cfc5b", - "packages/shared/src/telemetry/client.test.ts": "3ba900cdab5a1ac1dcc1dcea382bb790af32d895", - "packages/shared/src/telemetry/client.ts": "03a10a5550b542487543fbfd4a417e6eb316e11e", + "packages/shared/src/telemetry/client.test.ts": "5a95f2305a393c5b2e7750b10e0ed65da0f30cf8", + "packages/shared/src/telemetry/client.ts": "d6534ce8aaa6f69fb2dd03e12487db024e250a96", "packages/shared/src/telemetry/config.ts": "dfcd4d692cc06e71cb77f70b44fc05721eb330d1", "packages/shared/src/telemetry/connector-events.test.ts": "c060017c7a6a26e67aea56e5c9e36059be527070", - "packages/shared/src/telemetry/events.ts": "78f2031313fb9c82412b7a5ec6facf1d1a935300", + "packages/shared/src/telemetry/events.ts": "5a8bd387ad993db1b9dcbd0919200edb58eb68bd", "packages/shared/src/telemetry/generated/paperclip-telemetry.ts": "b44d37d34283fefa4fba8e9ac4d87682ba694926", - "packages/shared/src/telemetry/index.ts": "d6436ffd5ba9463d45c5500b7c4847f51679d170", + "packages/shared/src/telemetry/index.ts": "39ba76a46c323a30e40c0590dcbc31edebefbe9a", "packages/shared/src/telemetry/readme-contract.test.ts": "eec9d4511ddc3085a9af1a2dab6bf8487e49dfd7", "packages/shared/src/telemetry/retention.test.ts": "9d54db1371bf20f22b8d2f8373f84433107a7408", "packages/shared/src/telemetry/retention.ts": "023004d4e49f52cfb6fa8c7d32e674640704ebb4",