feat(omo-codex): wire Codex SessionStart telemetry for DAU/WAU/MAU
Adds a new Codex plugin component `telemetry` that emits a single omo_codex_daily_active event (reason: session_start) from every Codex SessionStart hook, with the same UTC-day deduplication, hashed installation identifier, and four-flag opt-out as the install-time event. Previously omo-codex telemetry only fired on install_completed, so DAU/WAU/MAU under-reported real Codex usage. - New plugin component packages/omo-codex/plugin/components/telemetry/ mirrors the rules/comment-checker/lsp pattern: own src/, tsc build, vitest tests, package.json (posthog-node dep), hooks/hooks.json. - src/codex-hook.ts wraps createPluginPostHog().trackActive(..., "session_start") with safeShutdown so Codex session startup never blocks on telemetry. - Plugin root hooks.json + workspaces register the new component alongside rules and ultrawork on SessionStart. - Aggregate test expectations updated to include the telemetry directory. - cross-package-equivalence.test.ts pins product-identity constants and shouldDisablePostHog behavior to stay byte-equivalent between the CLI installer (src/telemetry/) and the plugin runtime (plugin/components/telemetry/src/), so the two PostHog sources never drift on event name, distinct_id base, dedup file path, or opt-out flags. - PostHogActivityReason union in the CLI-side posthog.ts gains "session_start" so future CLI paths can emit the same reason without a type break.
This commit is contained in:
YeonGyu-Kim
@@ -0,0 +1,21 @@
|
||||
import { renameSync, unlinkSync, writeFileSync } from "node:fs";
|
||||
|
||||
export function writeFileAtomically(filePath: string, content: string): void {
|
||||
const tempPath = `${filePath}.tmp`;
|
||||
writeFileSync(tempPath, content, "utf-8");
|
||||
|
||||
try {
|
||||
renameSync(tempPath, filePath);
|
||||
} catch (error) {
|
||||
const isPermissionError =
|
||||
error instanceof Error && (error.message.includes("EPERM") || error.message.includes("EACCES"));
|
||||
|
||||
if (process.platform === "win32" && isPermissionError) {
|
||||
unlinkSync(filePath);
|
||||
renameSync(tempPath, filePath);
|
||||
return;
|
||||
}
|
||||
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,69 @@
|
||||
#!/usr/bin/env node
|
||||
import { stdin as processStdin, stdout as processStdout } from "node:process";
|
||||
|
||||
import { type CodexSessionStartInput, runSessionStartHook } from "./codex-hook.js";
|
||||
|
||||
const command = process.argv[2];
|
||||
const subcommand = process.argv[3];
|
||||
|
||||
if (command === "hook" && subcommand === "session-start") {
|
||||
await runHookCli();
|
||||
} else {
|
||||
process.stderr.write("Usage: codex-telemetry hook session-start\n");
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
async function runHookCli(): Promise<void> {
|
||||
const raw = await readStdin();
|
||||
if (raw.trim().length === 0) return;
|
||||
const parsed = parseHookInput(raw);
|
||||
if (!isCodexSessionStartInput(parsed)) return;
|
||||
const output = await runSessionStartHook(parsed);
|
||||
if (output.length > 0) {
|
||||
processStdout.write(output);
|
||||
}
|
||||
}
|
||||
|
||||
function parseHookInput(raw: string): unknown | undefined {
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(raw);
|
||||
return parsed;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function isCodexSessionStartInput(value: unknown): value is CodexSessionStartInput {
|
||||
return (
|
||||
isRecord(value) &&
|
||||
value["hook_event_name"] === "SessionStart" &&
|
||||
typeof value["session_id"] === "string" &&
|
||||
isStringOrNull(value["transcript_path"]) &&
|
||||
typeof value["cwd"] === "string" &&
|
||||
typeof value["model"] === "string" &&
|
||||
typeof value["permission_mode"] === "string" &&
|
||||
typeof value["source"] === "string"
|
||||
);
|
||||
}
|
||||
|
||||
function isStringOrNull(value: unknown): value is string | null {
|
||||
return typeof value === "string" || value === null;
|
||||
}
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function readStdin(): Promise<string> {
|
||||
return new Promise((resolve, reject) => {
|
||||
let data = "";
|
||||
processStdin.setEncoding("utf8");
|
||||
processStdin.on("data", (chunk: string) => {
|
||||
data += chunk;
|
||||
});
|
||||
processStdin.once("error", reject);
|
||||
processStdin.once("end", () => {
|
||||
resolve(data);
|
||||
});
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
import {
|
||||
type PostHogActivityReason,
|
||||
type PostHogClient,
|
||||
createPluginPostHog,
|
||||
getPostHogDistinctId,
|
||||
} from "./posthog.js";
|
||||
|
||||
export type CodexSessionStartInput = {
|
||||
session_id: string;
|
||||
transcript_path: string | null;
|
||||
cwd: string;
|
||||
hook_event_name: "SessionStart";
|
||||
model: string;
|
||||
permission_mode: string;
|
||||
source: "startup" | "resume" | "clear";
|
||||
};
|
||||
|
||||
export type CodexTelemetryHookOptions = {
|
||||
createClient?: () => PostHogClient;
|
||||
getDistinctId?: () => string;
|
||||
};
|
||||
|
||||
const SESSION_START_REASON: PostHogActivityReason = "session_start";
|
||||
|
||||
export async function runSessionStartHook(
|
||||
_input: CodexSessionStartInput,
|
||||
options: CodexTelemetryHookOptions = {},
|
||||
): Promise<string> {
|
||||
const createClient = options.createClient ?? createPluginPostHog;
|
||||
const getDistinctId = options.getDistinctId ?? getPostHogDistinctId;
|
||||
|
||||
const client = createClient();
|
||||
try {
|
||||
client.trackActive(getDistinctId(), SESSION_START_REASON);
|
||||
} catch {
|
||||
await safeShutdown(client);
|
||||
return "";
|
||||
}
|
||||
await safeShutdown(client);
|
||||
return "";
|
||||
}
|
||||
|
||||
async function safeShutdown(client: PostHogClient): Promise<void> {
|
||||
try {
|
||||
await client.shutdown();
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
import { accessSync, constants, mkdirSync } from "node:fs";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { CACHE_DIR_NAME } from "./product-identity.js";
|
||||
|
||||
type OsProvider = Pick<typeof os, "homedir" | "tmpdir">;
|
||||
|
||||
let osProviderOverride: OsProvider | null = null;
|
||||
|
||||
export function getOsProvider(): OsProvider {
|
||||
return osProviderOverride ?? os;
|
||||
}
|
||||
|
||||
/** @internal test-only */
|
||||
export function __setOsProviderForTesting(provider: OsProvider): void {
|
||||
osProviderOverride = provider;
|
||||
}
|
||||
|
||||
/** @internal test-only */
|
||||
export function __resetOsProviderForTesting(): void {
|
||||
osProviderOverride = null;
|
||||
}
|
||||
|
||||
function resolveWritableDirectory(preferredDir: string, fallbackSuffix: string): string {
|
||||
try {
|
||||
mkdirSync(preferredDir, { recursive: true });
|
||||
accessSync(preferredDir, constants.W_OK);
|
||||
return preferredDir;
|
||||
} catch {
|
||||
const fallbackDir = path.join(getOsProvider().tmpdir(), fallbackSuffix);
|
||||
mkdirSync(fallbackDir, { recursive: true });
|
||||
return fallbackDir;
|
||||
}
|
||||
}
|
||||
|
||||
export function getDataDir(): string {
|
||||
const preferredDataDir = process.env["XDG_DATA_HOME"] ?? path.join(getOsProvider().homedir(), ".local", "share");
|
||||
return resolveWritableDirectory(preferredDataDir, "omo-codex-data");
|
||||
}
|
||||
|
||||
export function getActivityStateDir(): string {
|
||||
return path.join(getDataDir(), CACHE_DIR_NAME);
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
import { DEFAULT_POSTHOG_API_KEY, DEFAULT_POSTHOG_HOST } from "./product-identity.js";
|
||||
|
||||
function normalizeEnvValue(value: string | undefined): string | undefined {
|
||||
return value?.trim().toLowerCase();
|
||||
}
|
||||
|
||||
function isDisableFlag(value: string | undefined): boolean {
|
||||
const normalized = normalizeEnvValue(value);
|
||||
return normalized === "1" || normalized === "true";
|
||||
}
|
||||
|
||||
function isTelemetryOptOutFlag(value: string | undefined): boolean {
|
||||
const normalized = normalizeEnvValue(value);
|
||||
return normalized === "0" || normalized === "false" || normalized === "no";
|
||||
}
|
||||
|
||||
export function shouldDisablePostHog(): boolean {
|
||||
return (
|
||||
isDisableFlag(process.env["OMO_DISABLE_POSTHOG"]) ||
|
||||
isTelemetryOptOutFlag(process.env["OMO_SEND_ANONYMOUS_TELEMETRY"]) ||
|
||||
isDisableFlag(process.env["OMO_CODEX_DISABLE_POSTHOG"]) ||
|
||||
isTelemetryOptOutFlag(process.env["OMO_CODEX_SEND_ANONYMOUS_TELEMETRY"])
|
||||
);
|
||||
}
|
||||
|
||||
export function getPostHogApiKey(): string {
|
||||
const explicit = process.env["POSTHOG_API_KEY"];
|
||||
if (explicit === undefined) {
|
||||
return DEFAULT_POSTHOG_API_KEY;
|
||||
}
|
||||
return explicit.trim();
|
||||
}
|
||||
|
||||
export function hasPostHogApiKey(): boolean {
|
||||
return getPostHogApiKey().length > 0;
|
||||
}
|
||||
|
||||
export function getPostHogHost(): string {
|
||||
return process.env["POSTHOG_HOST"]?.trim() || DEFAULT_POSTHOG_HOST;
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
import { existsSync, mkdirSync, readFileSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { writeFileAtomically } from "./atomic-write.js";
|
||||
import { getActivityStateDir } from "./data-path.js";
|
||||
|
||||
export type PostHogActivityState = {
|
||||
readonly lastActiveDayUTC?: string;
|
||||
};
|
||||
|
||||
export type PostHogActivityCaptureState = {
|
||||
readonly dayUTC: string;
|
||||
readonly captureDaily: boolean;
|
||||
};
|
||||
|
||||
const POSTHOG_ACTIVITY_STATE_FILE = "posthog-activity.json";
|
||||
|
||||
function getPostHogActivityStateFilePath(): string {
|
||||
return join(getActivityStateDir(), POSTHOG_ACTIVITY_STATE_FILE);
|
||||
}
|
||||
|
||||
function getUtcDayString(date: Date): string {
|
||||
return date.toISOString().slice(0, 10);
|
||||
}
|
||||
|
||||
function isPostHogActivityState(value: unknown): value is PostHogActivityState {
|
||||
return value !== null && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function readPostHogActivityState(): PostHogActivityState {
|
||||
const stateFilePath = getPostHogActivityStateFilePath();
|
||||
|
||||
if (!existsSync(stateFilePath)) {
|
||||
return {};
|
||||
}
|
||||
|
||||
try {
|
||||
const stateContent = readFileSync(stateFilePath, "utf-8");
|
||||
const stateJson: unknown = JSON.parse(stateContent);
|
||||
|
||||
if (!isPostHogActivityState(stateJson)) {
|
||||
return {};
|
||||
}
|
||||
|
||||
return stateJson;
|
||||
} catch {
|
||||
return {};
|
||||
}
|
||||
}
|
||||
|
||||
function writePostHogActivityState(nextState: PostHogActivityState): void {
|
||||
const stateDir = getActivityStateDir();
|
||||
const stateFilePath = getPostHogActivityStateFilePath();
|
||||
|
||||
try {
|
||||
mkdirSync(stateDir, { recursive: true });
|
||||
writeFileAtomically(stateFilePath, `${JSON.stringify(nextState, null, 2)}\n`);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
export function getPostHogActivityCaptureState(now: Date = new Date()): PostHogActivityCaptureState {
|
||||
const state = readPostHogActivityState();
|
||||
const dayUTC = getUtcDayString(now);
|
||||
const captureDaily = state.lastActiveDayUTC !== dayUTC;
|
||||
|
||||
if (captureDaily) {
|
||||
writePostHogActivityState({
|
||||
...state,
|
||||
lastActiveDayUTC: dayUTC,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
dayUTC,
|
||||
captureDaily,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,156 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import os from "node:os";
|
||||
|
||||
import { PostHog } from "posthog-node";
|
||||
|
||||
import { getPostHogApiKey, getPostHogHost, hasPostHogApiKey, shouldDisablePostHog } from "./env-flags.js";
|
||||
import { getPostHogActivityCaptureState } from "./posthog-activity-state.js";
|
||||
import {
|
||||
DEFAULT_POSTHOG_API_KEY,
|
||||
DEFAULT_POSTHOG_HOST,
|
||||
EVENT_NAME,
|
||||
PACKAGE_NAME,
|
||||
PRODUCT_NAME,
|
||||
getComponentVersion,
|
||||
} from "./product-identity.js";
|
||||
|
||||
export { DEFAULT_POSTHOG_API_KEY, DEFAULT_POSTHOG_HOST };
|
||||
|
||||
export type PostHogActivityReason = "session_start";
|
||||
|
||||
export type PostHogClient = {
|
||||
trackActive: (distinctId: string, reason: PostHogActivityReason) => void;
|
||||
shutdown: () => Promise<void>;
|
||||
};
|
||||
|
||||
type OsProvider = Pick<typeof os, "arch" | "cpus" | "hostname" | "platform" | "release" | "totalmem" | "type">;
|
||||
type ActivityStateProvider = typeof getPostHogActivityCaptureState;
|
||||
|
||||
let osProviderOverride: OsProvider | null = null;
|
||||
let activityStateProviderOverride: ActivityStateProvider | null = null;
|
||||
|
||||
const NO_OP_POSTHOG: PostHogClient = {
|
||||
trackActive: () => undefined,
|
||||
shutdown: async () => undefined,
|
||||
};
|
||||
|
||||
type PostHogCaptureEvent = Parameters<PostHog["capture"]>[0];
|
||||
|
||||
function resolveOsProvider(): OsProvider {
|
||||
return osProviderOverride ?? os;
|
||||
}
|
||||
|
||||
function resolveActivityStateProvider(): ActivityStateProvider {
|
||||
return activityStateProviderOverride ?? getPostHogActivityCaptureState;
|
||||
}
|
||||
|
||||
function getSafeCpuInfo(): { readonly count: number; readonly model: string | undefined } {
|
||||
try {
|
||||
const cpuInfo = resolveOsProvider().cpus();
|
||||
return {
|
||||
count: cpuInfo.length,
|
||||
model: cpuInfo[0]?.model,
|
||||
};
|
||||
} catch {
|
||||
return {
|
||||
count: 0,
|
||||
model: undefined,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
function getSharedProperties(): NonNullable<PostHogCaptureEvent["properties"]> {
|
||||
const osProvider = resolveOsProvider();
|
||||
const cpuInfo = getSafeCpuInfo();
|
||||
|
||||
return {
|
||||
platform: "omo-codex",
|
||||
product_name: PRODUCT_NAME,
|
||||
package_name: PACKAGE_NAME,
|
||||
package_version: getComponentVersion(),
|
||||
runtime: "node",
|
||||
runtime_version: process.version,
|
||||
source: "plugin",
|
||||
$os: osProvider.platform(),
|
||||
$os_version: osProvider.release(),
|
||||
os_arch: osProvider.arch(),
|
||||
os_type: osProvider.type(),
|
||||
cpu_count: cpuInfo.count,
|
||||
cpu_model: cpuInfo.model,
|
||||
total_memory_gb: Math.round(osProvider.totalmem() / 1024 / 1024 / 1024),
|
||||
locale: Intl.DateTimeFormat().resolvedOptions().locale,
|
||||
timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
|
||||
shell: process.env["SHELL"],
|
||||
ci: Boolean(process.env["CI"]),
|
||||
terminal: process.env["TERM_PROGRAM"],
|
||||
};
|
||||
}
|
||||
|
||||
export function createPluginPostHog(): PostHogClient {
|
||||
if (shouldDisablePostHog() || !hasPostHogApiKey()) {
|
||||
return NO_OP_POSTHOG;
|
||||
}
|
||||
|
||||
let client: PostHog;
|
||||
try {
|
||||
client = new PostHog(getPostHogApiKey(), {
|
||||
enableExceptionAutocapture: false,
|
||||
enableLocalEvaluation: false,
|
||||
strictLocalEvaluation: true,
|
||||
disableRemoteConfig: true,
|
||||
flushAt: 1,
|
||||
flushInterval: 0,
|
||||
host: getPostHogHost(),
|
||||
disableGeoip: false,
|
||||
});
|
||||
} catch {
|
||||
return NO_OP_POSTHOG;
|
||||
}
|
||||
|
||||
const sharedProperties = getSharedProperties();
|
||||
|
||||
return {
|
||||
trackActive: (distinctId, reason) => {
|
||||
const activityState = resolveActivityStateProvider()();
|
||||
if (!activityState.captureDaily) {
|
||||
return;
|
||||
}
|
||||
|
||||
client.capture({
|
||||
distinctId,
|
||||
event: EVENT_NAME,
|
||||
properties: {
|
||||
...sharedProperties,
|
||||
$process_person_profile: false,
|
||||
day_utc: activityState.dayUTC,
|
||||
reason,
|
||||
},
|
||||
});
|
||||
},
|
||||
shutdown: async () => client.shutdown(),
|
||||
};
|
||||
}
|
||||
|
||||
export function getPostHogDistinctId(): string {
|
||||
return createHash("sha256").update(`omo-codex:${resolveOsProvider().hostname()}`).digest("hex");
|
||||
}
|
||||
|
||||
/** @internal test-only */
|
||||
export function __setOsProviderForTesting(provider: OsProvider): void {
|
||||
osProviderOverride = provider;
|
||||
}
|
||||
|
||||
/** @internal test-only */
|
||||
export function __resetOsProviderForTesting(): void {
|
||||
osProviderOverride = null;
|
||||
}
|
||||
|
||||
/** @internal test-only */
|
||||
export function __setActivityStateProviderForTesting(provider: ActivityStateProvider): void {
|
||||
activityStateProviderOverride = provider;
|
||||
}
|
||||
|
||||
/** @internal test-only */
|
||||
export function __resetActivityStateProviderForTesting(): void {
|
||||
activityStateProviderOverride = null;
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
import { readFileSync } from "node:fs";
|
||||
|
||||
export const PRODUCT_NAME = "omo-codex";
|
||||
export const PACKAGE_NAME = "@oh-my-opencode/omo-codex";
|
||||
export const CACHE_DIR_NAME = "omo-codex";
|
||||
export const EVENT_NAME = "omo_codex_daily_active";
|
||||
export const LEGACY_PARENT_PACKAGE = "oh-my-opencode";
|
||||
export const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com";
|
||||
export const DEFAULT_POSTHOG_API_KEY = "phc_CFJhj5HyvA62QPhvyaUCtaq23aUfznnijg5VaaGkNk74";
|
||||
|
||||
type ComponentPackageManifest = { readonly version?: string };
|
||||
|
||||
function isComponentPackageManifest(value: unknown): value is ComponentPackageManifest {
|
||||
return value !== null && typeof value === "object" && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function readComponentVersionFromManifest(): string {
|
||||
try {
|
||||
const manifestUrl = new URL("../package.json", import.meta.url);
|
||||
const manifestText = readFileSync(manifestUrl, "utf-8");
|
||||
const parsed: unknown = JSON.parse(manifestText);
|
||||
if (isComponentPackageManifest(parsed) && typeof parsed.version === "string") {
|
||||
return parsed.version;
|
||||
}
|
||||
} catch {
|
||||
return "0.0.0";
|
||||
}
|
||||
return "0.0.0";
|
||||
}
|
||||
|
||||
const COMPONENT_VERSION_CACHE = readComponentVersionFromManifest();
|
||||
|
||||
export function getComponentVersion(): string {
|
||||
return COMPONENT_VERSION_CACHE;
|
||||
}
|
||||
Reference in New Issue
Block a user