Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
feat(analytics): send anonymous usage summaries (#60)
Leo63474598cf24
diff --git a/apps/mobile/src/features/home/HomeRouteScreen.tsx b/apps/mobile/src/features/home/HomeRouteScreen.tsxindex beabf66d9..119a3ad8f 100644--- a/apps/mobile/src/features/home/HomeRouteScreen.tsx+++ b/apps/mobile/src/features/home/HomeRouteScreen.tsx@@ -168,7 +168,10 @@ export function HomeRouteScreen() {onOpenSettings={() =>navigation.navigate("SettingsSheet", {screen: "SettingsContent",- params: { screen: "Settings" },+ params: {+ screen: "Settings",+ params: { environmentId: selectedEnvironmentId },+ },})}onProjectSortOrderChange={setProjectSortOrder}@@ -201,7 +204,10 @@ export function HomeRouteScreen() {onOpenSettings={() =>navigation.navigate("SettingsSheet", {screen: "SettingsContent",- params: { screen: "Settings" },+ params: {+ screen: "Settings",+ params: { environmentId: selectedEnvironmentId },+ },})}onProjectSortOrderChange={setProjectSortOrder}diff --git a/apps/mobile/src/features/layout/AdaptiveWorkspaceLayout.tsx b/apps/mobile/src/features/layout/AdaptiveWorkspaceLayout.tsxindex 9ea8eb88d..c846bebb1 100644--- a/apps/mobile/src/features/layout/AdaptiveWorkspaceLayout.tsx+++ b/apps/mobile/src/features/layout/AdaptiveWorkspaceLayout.tsx@@ -432,9 +432,14 @@ function AdaptiveWorkspaceLayoutContent(const handleOpenSettings = useCallback(() => {navigation.navigate("SettingsSheet", {screen: "SettingsContent",- params: { screen: "Settings" },+ params: {+ screen: "Settings",+ params: {+ environmentId: environmentId === null ? null : EnvironmentId.make(environmentId),+ },+ },});- }, [navigation]);+ }, [environmentId, navigation]);const handleStartNewTask = useCallback(() => {navigation.navigate("NewTaskSheet", { screen: "NewTask" });diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.logic.test.ts b/apps/mobile/src/features/settings/SettingsRouteScreen.logic.test.tsindex aec583d67..259eaf949 100644--- a/apps/mobile/src/features/settings/SettingsRouteScreen.logic.test.ts+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.logic.test.ts@@ -1,6 +1,11 @@import { describe, expect, it } from "vite-plus/test";-import { resolveAgentAwarenessPlatformPresentation } from "./SettingsRouteScreen.logic";+import { EnvironmentId } from "@t3tools/contracts";++import {+ resolveAgentAwarenessPlatformPresentation,+ resolveSettingsEnvironmentId,+} from "./SettingsRouteScreen.logic";describe("resolveAgentAwarenessPlatformPresentation", () => {it("explains that agent awareness settings are unavailable on Android", () => {@@ -17,3 +22,20 @@ describe("resolveAgentAwarenessPlatformPresentation", () => {});});});++describe("resolveSettingsEnvironmentId", () => {+ const first = EnvironmentId.make("server-a");+ const second = EnvironmentId.make("server-b");++ it("uses the selected environment when several are saved", () => {+ expect(resolveSettingsEnvironmentId(second, [first, second])).toBe(second);+ });++ it("does not guess when several environments are saved", () => {+ expect(resolveSettingsEnvironmentId(null, [first, second])).toBeNull();+ });++ it("uses the only saved environment when no selection is available", () => {+ expect(resolveSettingsEnvironmentId(null, [first])).toBe(first);+ });+});diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.logic.ts b/apps/mobile/src/features/settings/SettingsRouteScreen.logic.tsindex 94fa5965e..2b27a1b10 100644--- a/apps/mobile/src/features/settings/SettingsRouteScreen.logic.ts+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.logic.ts@@ -1,3 +1,5 @@+import type { EnvironmentId } from "@t3tools/contracts";+export function resolveAgentAwarenessPlatformPresentation(platform: string): {readonly supported: boolean;readonly subtitle: string | undefined;@@ -6,3 +8,17 @@ export function resolveAgentAwarenessPlatformPresentation(platform: string): {? { supported: true, subtitle: undefined }: { supported: false, subtitle: "iOS only" };}++export function resolveSettingsEnvironmentId(+ selectedEnvironmentId: EnvironmentId | null | undefined,+ availableEnvironmentIds: ReadonlyArray<EnvironmentId>,+): EnvironmentId | null {+ if (+ selectedEnvironmentId !== null &&+ selectedEnvironmentId !== undefined &&+ availableEnvironmentIds.includes(selectedEnvironmentId)+ ) {+ return selectedEnvironmentId;+ }+ return availableEnvironmentIds.length === 1 ? (availableEnvironmentIds[0] ?? null) : null;+}diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsxindex 39fe4234b..ad2811ffa 100644--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx@@ -1,9 +1,9 @@import { useAuth, useUser } from "@clerk/expo";import { useAtomSet, useAtomValue } from "@effect/atom-react";-import type { EnvironmentId } from "@t3tools/contracts";+import { EnvironmentId } from "@t3tools/contracts";import Constants from "expo-constants";import * as Notifications from "expo-notifications";-import { useNavigation } from "@react-navigation/native";+import { useNavigation, type StaticScreenProps } from "@react-navigation/native";import { NativeStackScreenOptions } from "../../native/StackHeader";import { SymbolView } from "../../components/AppSymbol";import * as Effect from "effect/Effect";@@ -44,10 +44,15 @@ import {runAppUpdateCheck,} from "../updates/app-updates";import { useSavedRemoteConnections } from "../../state/use-remote-environment-registry";+import { serverEnvironment } from "../../state/server";+import { useAtomCommand } from "../../state/use-atom-command";import { SettingsRow } from "./components/SettingsRow";import { SettingsSection } from "./components/SettingsSection";import { SettingsSwitchRow } from "./components/SettingsSwitchRow";-import { resolveAgentAwarenessPlatformPresentation } from "./SettingsRouteScreen.logic";+import {+ resolveAgentAwarenessPlatformPresentation,+ resolveSettingsEnvironmentId,+} from "./SettingsRouteScreen.logic";type NotificationStatus = "checking" | "enabled" | "disabled" | "unsupported";type LiveActivityStatus = "checking" | "enabled" | "disabled" | "signed-out" | "linking";@@ -65,8 +70,19 @@ function useDeviceRegistered(): boolean {return status === "registered";}-export function SettingsRouteScreen() {+type SettingsRouteParams = {+ readonly environmentId?: EnvironmentId | ReadonlyArray<string> | null;+};++export function SettingsRouteScreen({ route }: StaticScreenProps<SettingsRouteParams | undefined>) {const navigation = useNavigation();+ const rawEnvironmentId = route.params?.environmentId;+ const environmentId =+ typeof rawEnvironmentId === "string"+ ? EnvironmentId.make(rawEnvironmentId)+ : rawEnvironmentId?.[0] === undefined+ ? null+ : EnvironmentId.make(rawEnvironmentId[0]);return (<>@@ -96,16 +112,28 @@ export function SettingsRouteScreen() {}}/>)}- {hasCloudPublicConfig() ? <ConfiguredSettingsRouteScreen /> : <LocalSettingsRouteScreen />}+ {hasCloudPublicConfig() ? (+ <ConfiguredSettingsRouteScreen environmentId={environmentId} />+ ) : (+ <LocalSettingsRouteScreen environmentId={environmentId} />+ )}</>);}-function LocalSettingsRouteScreen() {+function LocalSettingsRouteScreen({+ environmentId,+}: {+ readonly environmentId: EnvironmentId | null;+}) {const insets = useSafeAreaInsets();const { savedConnectionsById } = useSavedRemoteConnections();const connections = Object.values(savedConnectionsById);const environmentCount = connections.length;+ const settingsEnvironmentId = resolveSettingsEnvironmentId(+ environmentId,+ connections.map((connection) => connection.environmentId),+ );return (<View collapsable={false} className="flex-1 bg-sheet">@@ -129,7 +157,7 @@ function LocalSettingsRouteScreen() {<ErrorsSettingsSection environmentId={connections[0]?.environmentId ?? null} />- <GeneralSettingsSection />+ <GeneralSettingsSection environmentId={settingsEnvironmentId} /><SettingsSection title="Appearance"><SettingsRow icon="paintbrush" label="Appearance" target="SettingsAppearance" />@@ -145,7 +173,11 @@ function LocalSettingsRouteScreen() {);}-function ConfiguredSettingsRouteScreen() {+function ConfiguredSettingsRouteScreen({+ environmentId,+}: {+ readonly environmentId: EnvironmentId | null;+}) {const preferencesResult = useAtomValue(mobilePreferencesAtom);const savePreferences = useAtomSet(updateMobilePreferencesAtom);const agentAwarenessPushAvailable = supportsAgentAwarenessPush();@@ -164,6 +196,10 @@ function ConfiguredSettingsRouteScreen() {const connections = useMemo(() => Object.values(savedConnectionsById), [savedConnectionsById]);const environmentCount = connections.length;+ const settingsEnvironmentId = resolveSettingsEnvironmentId(+ environmentId,+ connections.map((connection) => connection.environmentId),+ );const accountLabel = useMemo(() => {if (!isLoaded) return "Checking";if (!isSignedIn) return "Sign in";@@ -517,7 +553,7 @@ function ConfiguredSettingsRouteScreen() {<ErrorsSettingsSection environmentId={connections[0]?.environmentId ?? null} />- <GeneralSettingsSection />+ <GeneralSettingsSection environmentId={settingsEnvironmentId} /><SettingsSection title="Appearance"><SettingsRow icon="paintbrush" label="Appearance" target="SettingsAppearance" />@@ -559,7 +595,34 @@ function ErrorsSettingsSection({);}-function GeneralSettingsSection() {+function AnalyticsSettingsSwitch({ environmentId }: { readonly environmentId: EnvironmentId }) {+ const settings = useAtomValue(serverEnvironment.settingsValueAtom(environmentId));+ const updateSettings = useAtomCommand(serverEnvironment.updateSettings);+ const [saving, setSaving] = useState(false);++ return (+ <SettingsSwitchRow+ disabled={settings === null || saving}+ icon="chart.bar"+ label="Analytics"+ value={settings?.analyticsEnabled ?? true}+ onValueChange={async (analyticsEnabled) => {+ setSaving(true);+ try {+ await updateSettings({ environmentId, input: { patch: { analyticsEnabled } } });+ } finally {+ setSaving(false);+ }+ }}+ />+ );+}++function GeneralSettingsSection({+ environmentId,+}: {+ readonly environmentId: EnvironmentId | null;+}) {const preferencesResult = useAtomValue(mobilePreferencesAtom);const savePreferences = useAtomSet(updateMobilePreferencesAtom);const autoSettleOnMerge =@@ -576,6 +639,17 @@ function GeneralSettingsSection() {onValueChange={(value) => savePreferences({ autoSettleOnMerge: value })}/><SettingsRow icon="chart.bar.xaxis" label="Usage" target="SettingsUsage" />+ {environmentId === null ? (+ <SettingsSwitchRow+ disabled+ icon="chart.bar"+ label="Analytics"+ value+ onValueChange={() => {}}+ />+ ) : (+ <AnalyticsSettingsSwitch environmentId={environmentId} />+ )}</SettingsSection>);}diff --git a/apps/server/integration/providerService.integration.test.ts b/apps/server/integration/providerService.integration.test.tsindex 6089d22d9..4bffa9a43 100644--- a/apps/server/integration/providerService.integration.test.ts+++ b/apps/server/integration/providerService.integration.test.ts@@ -8,7 +8,6 @@ import * as FileSystem from "effect/FileSystem";import * as Layer from "effect/Layer";import * as Path from "effect/Path";import * as Queue from "effect/Queue";-import * as Ref from "effect/Ref";import * as Stream from "effect/Stream";import { ProviderAdapterRegistry } from "../src/provider/Services/ProviderAdapterRegistry.ts";@@ -25,7 +24,6 @@ import {} from "../src/provider/Services/ProviderService.ts";import * as ServerConfig from "../src/config.ts";import { ServerSettingsService } from "../src/serverSettings.ts";-import { AnalyticsService } from "../src/telemetry/Services/AnalyticsService.ts";import { SqlitePersistenceMemory } from "../src/persistence/Layers/Sqlite.ts";import * as ProviderSessionRuntime from "../src/persistence/ProviderSessionRuntime.ts";@@ -56,29 +54,7 @@ interface IntegrationFixture {readonly layer: Layer.Layer<ProviderService, unknown, never>;}-interface RecordedAnalyticsEvent {- readonly event: string;- readonly properties: Readonly<Record<string, unknown>> | undefined;-}--/**- * Analytics layer that keeps captured events in memory so tests can assert on- * telemetry payloads. `AnalyticsService.layerTest` discards them.- */-const makeRecordingAnalytics = Effect.gen(function* () {- const recorded = yield* Ref.make<ReadonlyArray<RecordedAnalyticsEvent>>([]);- const layer = Layer.succeed(- AnalyticsService,- AnalyticsService.of({- record: (event, properties) =>- Ref.update(recorded, (current) => [...current, { event, properties }]),- flush: Effect.void,- }),- );- return { layer, get: Ref.get(recorded) } as const;-});--const makeIntegrationFixture = (options?: { readonly analytics?: Layer.Layer<AnalyticsService> }) =>+const makeIntegrationFixture = () =>Effect.gen(function* () {const cwd = yield* makeWorkspaceDirectory;const harness = yield* makeTestProviderAdapterHarness();@@ -96,7 +72,6 @@ const makeIntegrationFixture = (options?: { readonly analytics?: Layer.Layer<AnaLayer.succeed(ProviderAdapterRegistry, registry),ServerConfig.layerTest(cwd, cwd).pipe(Layer.provide(NodeServices.layer)),ServerSettingsService.layerTest(DEFAULT_SERVER_SETTINGS),- options?.analytics ?? AnalyticsService.layerTest,Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers),).pipe(Layer.provide(SqlitePersistenceMemory));@@ -328,59 +303,3 @@ it.live("rolls back provider conversation state only", () =>}).pipe(Effect.provide(fixture.layer));}).pipe(Effect.provide(NodeServices.layer)),);--it.live("reports runtime mode per turn and on mode transitions", () =>- Effect.gen(function* () {- const analytics = yield* makeRecordingAnalytics;- const fixture = yield* makeIntegrationFixture({ analytics: analytics.layer });- const threadId = ThreadId.make("thread-integration-runtime-mode");-- yield* Effect.gen(function* () {- const provider = yield* ProviderService;- const startSession = (runtimeMode: "approval-required" | "full-access") =>- provider.startSession(threadId, {- threadId,- provider: ProviderDriverKind.make("codex"),- providerInstanceId: codexInstanceId,- cwd: fixture.cwd,- runtimeMode,- });-- yield* startSession("approval-required");- yield* runTurn({- provider,- harness: fixture.harness,- threadId,- userText: "supervised turn",- response: { events: codexTurnTextFixture },- });-- // Toggling the mode restarts the session, which is the only place the- // transition is observable.- yield* startSession("full-access");- yield* runTurn({- provider,- harness: fixture.harness,- threadId,- userText: "full access turn",- response: { events: codexTurnTextFixture },- });-- const recorded = yield* analytics.get;-- assert.deepEqual(- recorded- .filter((entry) => entry.event === "provider.turn.sent")- .map((entry) => entry.properties?.runtimeMode),- ["approval-required", "full-access"],- );-- assert.deepEqual(- recorded- .filter((entry) => entry.event === "provider.runtime_mode.changed")- .map((entry) => [entry.properties?.from, entry.properties?.to]),- [["approval-required", "full-access"]],- );- }).pipe(Effect.provide(fixture.layer));- }).pipe(Effect.provide(NodeServices.layer)),-);diff --git a/apps/server/src/config.ts b/apps/server/src/config.tsindex e781b99ed..0d62e3dd7 100644--- a/apps/server/src/config.ts+++ b/apps/server/src/config.ts@@ -43,6 +43,7 @@ export interface ServerDerivedPaths {readonly providerEventLogPath: string;readonly terminalLogsDir: string;readonly anonymousIdPath: string;+ readonly analyticsStatePath: string;readonly environmentIdPath: string;readonly serverRuntimeStatePath: string;readonly secretsDir: string;@@ -129,6 +130,7 @@ export const deriveServerPaths = Effect.fn(function* (providerEventLogPath: join(providerLogsDir, "events.log"),terminalLogsDir: join(logsDir, "terminals"),anonymousIdPath: join(stateDir, "anonymous-id"),+ analyticsStatePath: join(stateDir, "analytics.json"),environmentIdPath: join(stateDir, "environment-id"),serverRuntimeStatePath: join(stateDir, "server-runtime.json"),secretsDir: join(stateDir, "secrets"),@@ -151,6 +153,7 @@ export const ensureServerDirectories = Effect.fn(function* (derivedPaths: Serverfs.makeDirectory(path.dirname(derivedPaths.settingsPath), { recursive: true }),fs.makeDirectory(derivedPaths.providerStatusCacheDir, { recursive: true }),fs.makeDirectory(path.dirname(derivedPaths.anonymousIdPath), { recursive: true }),+ fs.makeDirectory(path.dirname(derivedPaths.analyticsStatePath), { recursive: true }),fs.makeDirectory(path.dirname(derivedPaths.serverRuntimeStatePath), { recursive: true }),],{ concurrency: "unbounded" },diff --git a/apps/server/src/provider/Layers/ProviderService.test.ts b/apps/server/src/provider/Layers/ProviderService.test.tsindex bd89dc4f8..3f8474c6d 100644--- a/apps/server/src/provider/Layers/ProviderService.test.ts+++ b/apps/server/src/provider/Layers/ProviderService.test.ts@@ -14,7 +14,6 @@ import type {} from "@t3tools/contracts";import {ApprovalRequestId,- EnvironmentId,EventId,ProviderDriverKind,ProviderInstanceId,@@ -60,7 +59,6 @@ import {} from "../../persistence/Layers/Sqlite.ts";import * as ServerConfig from "../../config.ts";import * as ServerSettings from "../../serverSettings.ts";-import * as AnalyticsService from "../../telemetry/AnalyticsService.ts";import { makeAdapterRegistryMock } from "../testUtils/providerAdapterRegistryMock.ts";const defaultServerSettingsLayer = ServerSettings.ServerSettingsService.layerTest();@@ -309,7 +307,6 @@ function makeProviderServiceLayer() {Layer.provide(directoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provideMerge(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -361,7 +358,6 @@ it.effect("ProviderServiceLive catches stopAll failures during shutdown", () =>Layer.provide(directoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provideMerge(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -421,7 +417,6 @@ it.effect("ProviderServiceLive rejects new sessions for disabled providers", ()Layer.provide(directoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -506,7 +501,6 @@ it.effect(Layer.provide(directoryLayer),Layer.provide(serverSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -577,7 +571,6 @@ it.effect("ProviderServiceLive rejects new sessions for disabled custom instanceLayer.provide(directoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -636,7 +629,6 @@ it.effect(Layer.provide(directoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -695,7 +687,6 @@ it.effect("ProviderServiceLive writes canonical events to the emitting thread seLayer.provide(directoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -756,7 +747,6 @@ it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", (Layer.provide(directoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -823,7 +813,6 @@ it.effect(Layer.provide(firstDirectoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -883,7 +872,6 @@ it.effect(Layer.provide(secondDirectoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -1530,7 +1518,6 @@ routing.layer("ProviderServiceLive routing", (it) => {Layer.provide(firstDirectoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -1569,7 +1556,6 @@ routing.layer("ProviderServiceLive routing", (it) => {Layer.provide(secondDirectoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -1638,7 +1624,6 @@ routing.layer("ProviderServiceLive routing", (it) => {Layer.provide(firstDirectoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -1672,7 +1657,6 @@ routing.layer("ProviderServiceLive routing", (it) => {Layer.provide(secondDirectoryLayer),Layer.provide(defaultServerSettingsLayer),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,@@ -2148,7 +2132,6 @@ describe("agent browser access", () => {Layer.provide(directoryLayer),Layer.provide(ServerSettings.ServerSettingsService.layerTest({ enableAgentBrowserAccess })),Layer.provide(serverConfigTestLayer),- Layer.provide(AnalyticsService.layerTest),Layer.provide(Layer.succeed(ProviderEventLoggers.ProviderEventLoggers,diff --git a/apps/server/src/provider/Layers/ProviderService.ts b/apps/server/src/provider/Layers/ProviderService.tsindex b8cd0df53..7a3bcee6e 100644--- a/apps/server/src/provider/Layers/ProviderService.ts+++ b/apps/server/src/provider/Layers/ProviderService.ts@@ -55,7 +55,6 @@ import * as ProviderService from "../Services/ProviderService.ts";import * as ProviderSessionDirectory from "../Services/ProviderSessionDirectory.ts";import { type EventNdjsonLogger } from "./EventNdjsonLogger.ts";import * as ProviderEventLoggers from "./ProviderEventLoggers.ts";-import * as AnalyticsService from "../../telemetry/AnalyticsService.ts";import * as McpProviderSession from "../../mcp/McpProviderSession.ts";import * as McpSessionRegistry from "../../mcp/McpSessionRegistry.ts";import * as ServerSettings from "../../serverSettings.ts";@@ -215,7 +214,6 @@ const correlateRuntimeEventWithInstance = (const makeProviderService = Effect.fn("makeProviderService")(function* (options?: ProviderServiceLiveOptions,) {- const analytics = yield* Effect.service(AnalyticsService.AnalyticsService);const serverConfig = yield* ServerConfig.ServerConfig;const eventLoggers = yield* ProviderEventLoggers.ProviderEventLoggers;// Options-provided logger wins (test overrides); otherwise we take whatever@@ -434,11 +432,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* ({ ...existing, providerInstanceId: bindingInstanceId },input.binding.threadId,);- yield* analytics.record("provider.session.recovered", {- provider: existing.provider,- strategy: "adopt-existing",- hasResumeCursor: existing.resumeCursor !== undefined,- });return { adapter, session: existing } as const;}}@@ -477,11 +470,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* ({ ...resumed, providerInstanceId: bindingInstanceId },input.binding.threadId,);- yield* analytics.record("provider.session.recovered", {- provider: resumed.provider,- strategy: "resume-thread",- hasResumeCursor: resumed.resumeCursor !== undefined,- });return { adapter, session: resumed } as const;}).pipe(withMetrics({@@ -515,7 +503,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (adapter,instanceId,threadId: input.threadId,- runtimeMode: binding.runtimeMode,isActive: true,} as const;}@@ -525,7 +512,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (adapter,instanceId,threadId: input.threadId,- runtimeMode: binding.runtimeMode,isActive: false,} as const;}@@ -538,7 +524,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (adapter: recovered.adapter,instanceId,threadId: input.threadId,- runtimeMode: recovered.session.runtimeMode,isActive: true,} as const;});@@ -560,11 +545,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (}yield* adapter.stopSession(input.threadId).pipe(- Effect.tap(() =>- analytics.record("provider.session.stopped", {- provider: adapter.provider,- }),- ),Effect.catchCause((cause) =>Effect.logWarning("provider.session.stop-stale-failed", {threadId: input.threadId,@@ -678,29 +658,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (yield* upsertSessionBinding(sessionWithInstance, threadId, {modelSelection: input.modelSelection,});- yield* analytics.record("provider.session.started", {- provider: sessionWithInstance.provider,- runtimeMode: input.runtimeMode,- hasResumeCursor: sessionWithInstance.resumeCursor !== undefined,- hasCwd: typeof effectiveCwd === "string" && effectiveCwd.trim().length > 0,- hasModel:- typeof input.modelSelection?.model === "string" &&- input.modelSelection.model.trim().length > 0,- });-- // Changing runtime mode restarts the session, so the transition is only- // observable here, by diffing against the mode the previous session for- // this thread was bound to. Recording it separately is what makes the- // "started supervised, switched to full access" funnel answerable.- const previousRuntimeMode = persistedBinding?.runtimeMode;- if (previousRuntimeMode !== undefined && previousRuntimeMode !== input.runtimeMode) {- yield* analytics.record("provider.runtime_mode.changed", {- provider: sessionWithInstance.provider,- from: previousRuntimeMode,- to: input.runtimeMode,- });- }-return sessionWithInstance;}).pipe(withMetrics({@@ -799,17 +756,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (lastRuntimeEventAt: yield* nowIso,},});- yield* analytics.record("provider.turn.sent", {- provider: routed.adapter.provider,- model: input.modelSelection?.model,- interactionMode: input.interactionMode,- // Session-start events alone skew runtime mode toward users who toggle- // often, since every toggle restarts the session. Recording it per turn- // gives a usage-weighted view and lets it cross with interactionMode.- runtimeMode: routed.runtimeMode,- attachmentCount: input.attachments.length,- hasInput: typeof input.input === "string" && input.input.trim().length > 0,- });return turn;}).pipe(withMetrics({@@ -849,9 +795,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* ("provider.turn_id": input.turnId,});yield* routed.adapter.interruptTurn(routed.threadId, input.turnId);- yield* analytics.record("provider.turn.interrupted", {- provider: routed.adapter.provider,- });}).pipe(withMetrics({counter: providerTurnsTotal,@@ -886,10 +829,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* ("provider.request_id": input.requestId,});yield* routed.adapter.respondToRequest(routed.threadId, input.requestId, input.decision);- yield* analytics.record("provider.request.responded", {- provider: routed.adapter.provider,- decision: input.decision,- });}).pipe(withMetrics({counter: providerTurnsTotal,@@ -969,9 +908,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (activeTurnId: null,},});- yield* analytics.record("provider.session.stopped", {- provider: routed.adapter.provider,- });}).pipe(withMetrics({counter: providerSessionsTotal,@@ -1103,10 +1039,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* ("provider.rollback_turns": input.numTurns,});yield* routed.adapter.rollbackThread(routed.threadId, input.numTurns);- yield* analytics.record("provider.conversation.rolled_back", {- provider: routed.adapter.provider,- turns: input.numTurns,- });}).pipe(withMetrics({counter: providerTurnsTotal,@@ -1160,7 +1092,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* ();const runStopAll = Effect.fn("runStopAll")(function* () {- const threadIds = yield* directory.listThreadIds();const currentAdapters = yield* getAdapterEntries;const activeSessions = yield* Effect.forEach(currentAdapters, ([instanceId, adapter]) =>adapter.listSessions().pipe(@@ -1203,10 +1134,6 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (});}),).pipe(Effect.asVoid);- yield* analytics.record("provider.sessions.stopped_all", {- sessionCount: threadIds.length,- });- yield* analytics.flush;});yield* Effect.addFinalizer(() =>diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.tsindex fe8504c78..7436b676c 100644--- a/apps/server/src/server.test.ts+++ b/apps/server/src/server.test.ts@@ -416,7 +416,6 @@ const buildAppUnderTest = (options?: {>;terminalManager?: Partial<TerminalManager.TerminalManager["Service"]>;orchestrationEngine?: Partial<OrchestrationEngine.OrchestrationEngineService["Service"]>;- analyticsService?: Partial<AnalyticsService.AnalyticsService["Service"]>;projectionSnapshotQuery?: Partial<ProjectionSnapshotQuery.ProjectionSnapshotQuery["Service"]>;projectionBots?: Partial<ProjectionBots.ProjectionBotRepositoryShape>;botUsageLedger?: Partial<BotUsageLedgerShape>;@@ -893,9 +892,7 @@ const buildAppUnderTest = (options?: {Layer.provide(UsageService.layerTest),Layer.provide(Layer.mock(AnalyticsService.AnalyticsService)({- record: () => Effect.void,flush: Effect.void,- ...options?.layers?.analyticsService,}),),Layer.provide(@@ -5439,101 +5436,6 @@ it.layer(NodeServices.layer)("server router seam", (it) => {}).pipe(Effect.provide(NodeHttpServer.layerTest)),);- it.effect("records thread analytics only after a client command succeeds", () =>- Effect.gen(function* () {- const effects: string[] = [];- const analyticsProperties: Array<Readonly<Record<string, unknown>> | undefined> = [];- const failedCommandId = CommandId.make("cmd-thread-create-failed");-- yield* buildAppUnderTest({- layers: {- analyticsService: {- record: (event, properties) =>- Effect.sync(() => {- effects.push(`analytics:${event}`);- analyticsProperties.push(properties);- }),- },- orchestrationEngine: {- dispatch: (command) =>- Effect.sync(() => effects.push(`dispatch:${command.commandId}`)).pipe(- Effect.flatMap(() =>- command.commandId === failedCommandId- ? Effect.fail(- new OrchestrationListenerCallbackError({- listener: "domain-event",- detail: "thread creation failed",- }),- )- : Effect.succeed({ sequence: 1 }),- ),- ),- },- },- });-- const createThreadCommand = (commandId: CommandId, threadId: ThreadId) =>- ({- type: "thread.create",- commandId,- threadId,- projectId: defaultProjectId,- title: "Analytics test",- modelSelection: defaultModelSelection,- runtimeMode: "full-access",- interactionMode: "default",- branch: null,- worktreePath: null,- createdAt: "2026-01-01T00:00:00.000Z",- }) as const;-- const wsUrl = yield* getWsServerUrl(- "/ws?clientSurface=mobile&clientAppVersion=1.2.3&clientOs=iOS&clientOsMajorVersion=18&clientDeviceModel=iPhone+15+Pro",- );- yield* Effect.scoped(- withWsRpcClient(wsUrl, (client) =>- Effect.gen(function* () {- const failed = yield* client[ORCHESTRATION_WS_METHODS.dispatchCommand](- createThreadCommand(failedCommandId, ThreadId.make("thread-create-failed")),- ).pipe(Effect.result);-- assert.equal(failed._tag, "Failure");- assert.deepEqual(effects, [- "analytics:client.connected",- "dispatch:cmd-thread-create-failed",- ]);-- const succeeded = yield* client[ORCHESTRATION_WS_METHODS.dispatchCommand](- createThreadCommand(- CommandId.make("cmd-thread-create-succeeded"),- ThreadId.make("thread-create-succeeded"),- ),- );-- assert.equal(succeeded.sequence, 1);- }),- ),- );-- assert.deepEqual(effects, [- "analytics:client.connected",- "dispatch:cmd-thread-create-failed",- "dispatch:cmd-thread-create-succeeded",- "analytics:client.thread.started",- ]);- assert.deepEqual(analyticsProperties, [- {- surface: "mobile",- appVersion: "1.2.3",- os: "iOS",- osMajorVersion: 18,- deviceModel: "iPhone 15 Pro",- },- { surface: "mobile", appVersion: "1.2.3" },- ]);- }).pipe(Effect.provide(NodeHttpServer.layerTest)),- );-it.effect("routes websocket rpc projects.writeFile errors", () =>Effect.gen(function* () {const fs = yield* FileSystem.FileSystem;diff --git a/apps/server/src/server.ts b/apps/server/src/server.tsindex 9c9d6b50a..9025f5583 100644--- a/apps/server/src/server.ts+++ b/apps/server/src/server.ts@@ -79,7 +79,6 @@ import * as VcsStatusBroadcaster from "./vcs/VcsStatusBroadcaster.ts";import * as GitWorkflowService from "./git/GitWorkflowService.ts";import * as ReviewService from "./review/ReviewService.ts";import * as SourceControlProviderRegistry from "./sourceControl/SourceControlProviderRegistry.ts";-import * as SourceControlRateLimit from "./sourceControl/SourceControlRateLimit.ts";import * as SourceControlRepositoryService from "./sourceControl/SourceControlRepositoryService.ts";import * as ProjectSetupScriptRunner from "./project/ProjectSetupScriptRunner.ts";import { ObservabilityLive } from "./observability/Layers/Observability.ts";@@ -148,6 +147,11 @@ const ServerSettingsLayerLive = ServerSettings.layer.pipe(Layer.provideMerge(SqlitePersistenceLayerLive),);+const AnalyticsLayerLive = AnalyticsService.layer.pipe(+ Layer.provide(ServerSettingsLayerLive),+ Layer.provide(SqlitePersistenceLayerLive),+);+const NativeTelemetryLayerLive = NativeTelemetryClient.layer.pipe(Layer.provide(ResourceMonitorBinary.layer),);@@ -435,7 +439,7 @@ const RuntimeDependenciesLive = RuntimeCoreDependenciesLive.pipe(Layer.provideMerge(ResourceDiagnosticsLayerLive),Layer.provideMerge(UsageLayerLive),Layer.provideMerge(TraceDiagnostics.layer),- Layer.provideMerge(AnalyticsService.layer),+ Layer.provideMerge(AnalyticsLayerLive),Layer.provideMerge(ExternalLauncher.layer),Layer.provideMerge(RemoteOpenTargets.layer),Layer.provideMerge(ServerLifecycleEvents.layer),diff --git a/apps/server/src/serverRuntimeStartup.test.ts b/apps/server/src/serverRuntimeStartup.test.tsindex 9a1b79cd4..71652257a 100644--- a/apps/server/src/serverRuntimeStartup.test.ts+++ b/apps/server/src/serverRuntimeStartup.test.ts@@ -13,7 +13,6 @@ import * as Stream from "effect/Stream";import * as ServerConfig from "./config.ts";import * as OrchestrationEngine from "./orchestration/Services/OrchestrationEngine.ts";import * as ProjectionSnapshotQuery from "./orchestration/Services/ProjectionSnapshotQuery.ts";-import * as AnalyticsService from "./telemetry/AnalyticsService.ts";import * as ServerRuntimeStartup from "./serverRuntimeStartup.ts";it("uses the canonical Codex default for auto-bootstrapped model selection", () => {@@ -70,44 +69,6 @@ it.effect("enqueueCommand fails queued work when readiness fails", () =>),);-it.effect("launchStartupHeartbeat does not block the caller while counts are loading", () =>- Effect.scoped(- Effect.gen(function* () {- const releaseCounts = yield* Deferred.make<void, never>();-- yield* ServerRuntimeStartup.launchStartupHeartbeat.pipe(- Effect.provideService(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {- getCommandReadModel: () => Effect.die("unused"),- getSnapshot: () => Effect.die("unused"),- getShellSnapshot: () => Effect.die("unused"),- getArchivedShellSnapshot: () => Effect.die("unused"),- getSnapshotSequence: () => Effect.die("unused"),- getCounts: () =>- Deferred.await(releaseCounts).pipe(- Effect.as({- projectCount: 2,- threadCount: 3,- }),- ),- getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),- getProjectShellById: () => Effect.succeed(Option.none()),- getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),- getThreadCheckpointContext: () => Effect.succeed(Option.none()),- getFullThreadDiffContext: () => Effect.succeed(Option.none()),- getThreadShellById: () => Effect.succeed(Option.none()),- getThreadDetailById: () => Effect.succeed(Option.none()),- getThreadDetailSnapshot: () => Effect.succeed(Option.none()),- searchThreads: () => Effect.succeed({ matches: [] }),- }),- Effect.provideService(AnalyticsService.AnalyticsService, {- record: () => Effect.void,- flush: Effect.void,- }),- );- }),- ),-);-it.effect("resolveWelcomeBase derives cwd and project name from server config", () =>Effect.gen(function* () {const welcome = yield* ServerRuntimeStartup.resolveWelcomeBase.pipe(diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.tsindex fb78d393b..76b7de067 100644--- a/apps/server/src/serverRuntimeStartup.ts+++ b/apps/server/src/serverRuntimeStartup.ts@@ -31,7 +31,6 @@ import * as ProjectionSnapshotQuery from "./orchestration/Services/ProjectionSnaimport * as OrchestrationReactor from "./orchestration/Services/OrchestrationReactor.ts";import * as ServerLifecycleEvents from "./serverLifecycleEvents.ts";import * as ServerSettings from "./serverSettings.ts";-import * as AnalyticsService from "./telemetry/AnalyticsService.ts";import * as ServerEnvironment from "./environment/ServerEnvironment.ts";import * as EnvironmentAuth from "./auth/EnvironmentAuth.ts";import * as AgentController from "./provider/Services/AgentController.ts";@@ -135,37 +134,6 @@ export const makeCommandGate = Effect.gen(function* () {} satisfies CommandGate;});-export const recordStartupHeartbeat = Effect.gen(function* () {- const analytics = yield* AnalyticsService.AnalyticsService;- const projectionSnapshotQuery = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;-- const { threadCount, projectCount } = yield* projectionSnapshotQuery.getCounts().pipe(- Effect.catch((cause) =>- Effect.logWarning("failed to gather startup projection counts for telemetry", {- cause,- }).pipe(- Effect.as({- threadCount: 0,- projectCount: 0,- }),- ),- ),- );-- yield* analytics.record("server.boot.heartbeat", {- threadCount,- projectCount,- });-});--export const launchStartupHeartbeat = recordStartupHeartbeat.pipe(- Effect.annotateSpans({ "startup.phase": "heartbeat.record" }),- Effect.withSpan("server.startup.heartbeat.record"),- Effect.ignoreCause({ log: true }),- Effect.forkScoped,- Effect.asVoid,-);-export const getAutoBootstrapDefaultModelSelection = (): ModelSelection => ({instanceId: ProviderInstanceId.make("codex"),model: DEFAULT_MODEL,@@ -498,12 +466,6 @@ export const make = (options?: StartupOptions) =>yield* forkParked(Effect.gen(function* () {- yield* Effect.logDebug("startup phase: recording startup heartbeat");- yield* recordStartupHeartbeat.pipe(- Effect.annotateSpans({ "startup.phase": "heartbeat.record" }),- Effect.withSpan("server.startup.heartbeat.record"),- Effect.ignoreCause({ log: true }),- );if (serverConfig.startupPresentation === "headless") {const accessInfo = yield* issueHeadlessServeAccessInfo();yield* runStartupPhase(diff --git a/apps/server/src/telemetry/AnalyticsService.test.ts b/apps/server/src/telemetry/AnalyticsService.test.tsindex afdd06f4e..461d943e9 100644--- a/apps/server/src/telemetry/AnalyticsService.test.ts+++ b/apps/server/src/telemetry/AnalyticsService.test.ts@@ -1,122 +1,475 @@import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";import * as NodeServices from "@effect/platform-node/NodeServices";+import { USAGE_3H_COUNTER_KEYS, USAGE_BASE_COUNTER_KEYS } from "@t3tools/contracts";import { assert, it } from "@effect/vitest";import * as ConfigProvider from "effect/ConfigProvider";+import * as DateTime from "effect/DateTime";import * as Effect from "effect/Effect";+import * as FileSystem from "effect/FileSystem";import * as Layer from "effect/Layer";+import * as Schema from "effect/Schema";+import * as SqlClient from "effect/unstable/sql/SqlClient";import * as HttpServer from "effect/unstable/http/HttpServer";import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";import * as ServerConfig from "../config.ts";-import { getTelemetryIdentifier } from "./Identify.ts";+import { SqlitePersistenceMemory } from "../persistence/Layers/Sqlite.ts";+import * as ServerSettings from "../serverSettings.ts";import * as AnalyticsService from "./AnalyticsService.ts";-interface RecordedBatchRequest {- readonly path: string;- readonly body: {- readonly batch?: ReadonlyArray<{- readonly event?: string;- readonly properties?: {- readonly index?: number;- readonly clientType?: string;- };- }>;- } | null;-}+const encodeJson = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));+const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown));-interface RecordedBatchBody {- readonly batch: ReadonlyArray<{- readonly event?: string;- readonly properties?: {- readonly index?: number;- readonly clientType?: string;- };+interface StoredState {+ readonly installationId: string;+ readonly cursorBucketStart: string;+ readonly deliveryDay: string;+ readonly deliveredToday: number;+ readonly firstActiveInstallReported: boolean;+ readonly pending: ReadonlyArray<{+ readonly properties: { readonly $insert_id: string; readonly bucket_start: string };}>;}-it.layer(NodeServices.layer)("AnalyticsService test", (it) => {- it.effect("flush drains all buffered events across multiple batches", () =>+const makeLayers = (serverConfigLayer: ReturnType<typeof ServerConfig.ServerConfig.layerTest>) =>+ AnalyticsService.layer.pipe(+ Layer.provideMerge(serverConfigLayer),+ Layer.provideMerge(ServerSettings.layerTest()),+ Layer.provideMerge(SqlitePersistenceMemory),+ Layer.provideMerge(NodeHttpServer.layerTest),+ );++const readState = (encoded: string): StoredState => decodeJson(encoded) as StoredState;++const pendingEvent = {+ event: "usage_3h",+ distinct_id: "0f64da24-2c54-4d2a-9d68-f117c4e78e01",+ properties: {+ app_version: "1.0.0",+ operating_system: "darwin",+ architecture: "arm64",+ client_type: "web",+ provider: "codex",+ sandbox_provider: "local",+ bucket_start: "2026-08-31T18:00:00.000Z",+ new_installations: 0,+ bots_created: 0,+ bots_deleted: 0,+ bots_total: 1,+ user_messages: 1,+ bot_replies: 0,+ failed_turns: 0,+ group_messages: 0,+ external_messages: 0,+ voice_sessions: 0,+ browser_tasks: 0,+ routines_run: 0,+ routine_failures: 0,+ connector_calls: 0,+ connector_failures: 0,+ approvals_requested: 0,+ approvals_accepted: 0,+ approvals_rejected: 0,+ ...Object.fromEntries(+ USAGE_3H_COUNTER_KEYS.slice(USAGE_BASE_COUNTER_KEYS.length).map((key) => [key, 0]),+ ),+ $process_person_profile: false,+ $geoip_disable: true,+ $ip: "0.0.0.0",+ $insert_id: "a".repeat(64),+ },+ timestamp: "2026-08-31T21:00:00.000Z",+} as const;++it.layer(NodeServices.layer)("anonymous analytics", (it) => {+ it.effect(+ "persists closed buckets, retries with one insert id, skips empty buckets, and opts out",+ () =>+ Effect.gen(function* () {+ const captured: unknown[] = [];+ let attempts = 0;+ const serverConfigLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {+ prefix: "akeru-analytics-",+ });+ const configLayer = ConfigProvider.layer(+ ConfigProvider.fromUnknown({+ T3CODE_TELEMETRY_ENABLED: true,+ T3CODE_POSTHOG_KEY: "phc_test",+ T3CODE_POSTHOG_HOST: "http://localhost",+ }),+ );+ const analyticsLayer = makeLayers(serverConfigLayer).pipe(Layer.provide(configLayer));+ const batchServerLayer = HttpServer.serve(+ Effect.gen(function* () {+ const request = yield* HttpServerRequest.HttpServerRequest;+ captured.push(yield* request.json);+ attempts += 1;+ return attempts === 1+ ? HttpServerResponse.empty({ status: 503 })+ : HttpServerResponse.jsonUnsafe({});+ }),+ );++ yield* Effect.gen(function* () {+ yield* Layer.launch(batchServerLayer).pipe(Effect.forkScoped);+ const config = yield* ServerConfig.ServerConfig;+ const fs = yield* FileSystem.FileSystem;+ const sql = yield* SqlClient.SqlClient;+ const settings = yield* ServerSettings.ServerSettingsService;+ const analytics = yield* AnalyticsService.AnalyticsService;+ const currentStart = AnalyticsService.bucketStartAt(+ DateTime.toEpochMillis(yield* DateTime.now),+ );+ const firstStart = DateTime.formatIso(+ DateTime.subtract(DateTime.makeUnsafe(currentStart), { hours: 6 }),+ );+ const eventAt = DateTime.formatIso(+ DateTime.add(DateTime.makeUnsafe(firstStart), { minutes: 1 }),+ );+ const secondEventAt = DateTime.formatIso(+ DateTime.add(DateTime.makeUnsafe(firstStart), { hours: 3, minutes: 1 }),+ );+ const installationId = "0f64da24-2c54-4d2a-9d68-f117c4e78e01";++ yield* fs.writeFileString(+ config.analyticsStatePath,+ encodeJson({+ version: 1,+ installationId,+ cursorBucketStart: firstStart,+ deliveryDay: currentStart.slice(0, 10),+ deliveredToday: 0,+ firstActiveInstallReported: false,+ pending: [],+ }),+ );+ yield* fs.writeFileString(config.anonymousIdPath, "legacy-provider-derived-id");+ yield* sql`+ INSERT INTO orchestration_events (+ event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,+ command_id, causation_event_id, correlation_id, actor_kind, payload_json, metadata_json+ ) VALUES (+ 'event-analytics-message', 'thread', 'thread-analytics', 0, 'thread.message-sent',+ ${eventAt}, NULL, NULL, NULL, 'client',+ ${encodeJson({ role: "user", streaming: false })},+ ${encodeJson({ origin: { surface: "mobile" } })}+ )+ `;+ yield* sql`+ INSERT INTO projection_bots (+ bot_id, name, title, avatar_json, engine_json, sandbox, group_id,+ archived_at, created_at, updated_at+ ) VALUES (+ 'bot-analytics', 'Analytics test bot', 'Test', '{}',+ '{"provider":"codex"}', 'local', NULL, NULL, ${eventAt}, ${eventAt}+ )+ `;+ yield* sql`+ INSERT INTO projection_turns (+ thread_id, turn_id, state, requested_at, checkpoint_files_json, responding_bot_id+ ) VALUES (+ 'thread-analytics', 'turn-analytics', 'completed', ${eventAt}, '[]', 'bot-analytics'+ )+ `;+ yield* sql`+ INSERT INTO orchestration_events (+ event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,+ command_id, causation_event_id, correlation_id, actor_kind, payload_json, metadata_json+ ) VALUES (+ 'event-analytics-no-sandbox-turn', 'thread', 'thread-no-sandbox', 0,+ 'thread.turn-start-requested', ${eventAt}, NULL, NULL, NULL, 'client',+ ${encodeJson({})}, '{}'+ )+ `;+ yield* sql`+ INSERT INTO orchestration_events (+ event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,+ command_id, causation_event_id, correlation_id, actor_kind, payload_json, metadata_json+ ) VALUES (+ 'event-analytics-web-search', 'thread', 'thread-analytics', 2,+ 'thread.activity-appended', ${eventAt}, NULL, NULL, NULL, 'provider',+ ${encodeJson({+ activity: {+ kind: "tool.completed",+ turnId: "turn-analytics",+ payload: { itemType: "web_search" },+ },+ })},+ '{}'+ )+ `;+ yield* sql`+ INSERT INTO orchestration_events (+ event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,+ command_id, causation_event_id, correlation_id, actor_kind, payload_json, metadata_json+ ) VALUES (+ 'event-analytics-turn-start', 'thread', 'thread-analytics', 3,+ 'thread.turn-start-requested', ${eventAt}, NULL, NULL, NULL, 'client',+ ${encodeJson({ respondingBotId: "bot-analytics" })},+ '{}'+ )+ `;+ yield* sql`+ INSERT INTO orchestration_events (+ event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,+ command_id, causation_event_id, correlation_id, actor_kind, payload_json, metadata_json+ ) VALUES (+ 'event-analytics-tool', 'thread', 'thread-analytics', 1, 'thread.activity-appended',+ ${eventAt}, NULL, NULL, NULL, 'provider',+ ${encodeJson({+ activity: {+ kind: "tool.completed",+ payload: { itemType: "mcp_tool_call" },+ },+ })},+ '{}'+ )+ `;+ yield* sql`+ INSERT INTO projection_mcp_servers (+ mcp_server_id, name, transport, command, args_json, url, enabled, created_at, updated_at+ ) VALUES (+ 'builtin-github', 'GitHub', 'stdio', 'github-mcp', NULL, NULL, 1,+ ${eventAt}, ${eventAt}+ )+ `;+ yield* sql`+ INSERT INTO orchestration_events (+ event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,+ command_id, causation_event_id, correlation_id, actor_kind, payload_json, metadata_json+ ) VALUES (+ 'event-analytics-second-message', 'thread', 'thread-analytics', 4,+ 'thread.message-sent', ${secondEventAt}, NULL, NULL, NULL, 'client',+ ${encodeJson({ role: "user", streaming: false })},+ ${encodeJson({ origin: { surface: "mobile" } })}+ )+ `;++ yield* analytics.flush;+ const failedState = readState(yield* fs.readFileString(config.analyticsStatePath));+ assert.equal(failedState.pending.length, 2);+ assert.equal(failedState.cursorBucketStart, currentStart);+ assert.isFalse(yield* fs.exists(config.anonymousIdPath));++ yield* analytics.flush;+ const deliveredState = readState(yield* fs.readFileString(config.analyticsStatePath));+ assert.equal(deliveredState.pending.length, 0);+ assert.equal(captured.length, 2);++ const requests = captured as Array<{+ readonly api_key: string;+ readonly batch: ReadonlyArray<{+ readonly event: string;+ readonly distinct_id: string;+ readonly properties: {+ readonly $insert_id: string;+ readonly $process_person_profile: boolean;+ readonly $geoip_disable: boolean;+ readonly $ip: string;+ readonly user_messages: number;+ readonly new_installations: number;+ readonly client_type: string;+ readonly tool_calls_mcp_tool_call: number;+ readonly browser_searches_codex: number;+ readonly provider_turns_codex: number;+ readonly sandbox_turns_local: number;+ readonly sandbox_turns_none: number;+ readonly plugin_enabled_github: number;+ };+ }>;+ }>;+ assert.deepEqual(Object.keys(requests[0] ?? {}).toSorted(), ["api_key", "batch"]);+ assert.equal(requests[0]?.api_key, "phc_test");+ assert.equal(requests[0]?.batch.length, 2);+ assert.equal(requests[0]?.batch[0]?.event, "usage_3h");+ assert.equal(requests[0]?.batch[0]?.distinct_id, installationId);+ assert.equal(+ requests[0]?.batch[0]?.properties.$insert_id,+ requests[1]?.batch[0]?.properties.$insert_id,+ );+ assert.equal(requests[0]?.batch[0]?.properties.user_messages, 1);+ assert.equal(requests[0]?.batch[0]?.properties.new_installations, 1);+ assert.equal(requests[0]?.batch[1]?.properties.new_installations, 0);+ assert.equal(requests[0]?.batch[0]?.properties.client_type, "mobile");+ assert.equal(requests[0]?.batch[0]?.properties.tool_calls_mcp_tool_call, 1);+ assert.equal(requests[0]?.batch[0]?.properties.browser_searches_codex, 1);+ assert.equal(requests[0]?.batch[0]?.properties.provider_turns_codex, 1);+ assert.equal(requests[0]?.batch[0]?.properties.sandbox_turns_local, 1);+ assert.equal(requests[0]?.batch[0]?.properties.sandbox_turns_none, 1);+ assert.equal(requests[0]?.batch[0]?.properties.plugin_enabled_github, 1);+ assert.isFalse(requests[0]?.batch[0]?.properties.$process_person_profile);+ assert.isTrue(requests[0]?.batch[0]?.properties.$geoip_disable);+ assert.equal(requests[0]?.batch[0]?.properties.$ip, "0.0.0.0");+ assert.deepEqual(+ Object.keys(requests[0]?.batch[0]?.properties ?? {}).toSorted(),+ [+ ...USAGE_3H_COUNTER_KEYS,+ "app_version",+ "operating_system",+ "architecture",+ "client_type",+ "provider",+ "sandbox_provider",+ "bucket_start",+ "$process_person_profile",+ "$geoip_disable",+ "$ip",+ "$insert_id",+ ].toSorted(),+ );++ yield* fs.writeFileString(+ config.analyticsStatePath,+ encodeJson({+ ...deliveredState,+ pending: Array.from({ length: 9 }, () => pendingEvent),+ }),+ );+ yield* analytics.flush;+ yield* analytics.flush;+ const quotaState = readState(yield* fs.readFileString(config.analyticsStatePath));+ assert.equal(captured.length, 3);+ assert.equal((captured[2] as { readonly batch: ReadonlyArray<unknown> }).batch.length, 6);+ assert.equal(quotaState.pending.length, 3);+ assert.equal(quotaState.deliveredToday, 8);++ yield* settings.updateSettings({ analyticsEnabled: false });+ yield* analytics.flush;+ assert.isFalse(yield* fs.exists(config.analyticsStatePath));+ }).pipe(Effect.provide(analyticsLayer));+ }),+ );++ for (const [name, environment] of [+ ["development", { NODE_ENV: "development", T3CODE_POSTHOG_KEY: "phc_test" }],+ ["test", { NODE_ENV: "test", T3CODE_POSTHOG_KEY: "phc_test" }],+ ["CI", { CI: true, T3CODE_POSTHOG_KEY: "phc_test" }],+ ] as const) {+ it.effect(`does not create analytics state by default in ${name}`, () =>+ Effect.gen(function* () {+ const serverConfigLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {+ prefix: `akeru-analytics-${name}-`,+ });+ const analyticsLayer = makeLayers(serverConfigLayer).pipe(+ Layer.provide(ConfigProvider.layer(ConfigProvider.fromUnknown(environment))),+ );++ yield* Effect.gen(function* () {+ const config = yield* ServerConfig.ServerConfig;+ const fs = yield* FileSystem.FileSystem;+ const analytics = yield* AnalyticsService.AnalyticsService;+ yield* analytics.flush;+ assert.isFalse(yield* fs.exists(config.analyticsStatePath));+ }).pipe(Effect.provide(analyticsLayer));+ }),+ );+ }++ it.effect("deletes analytics state when the environment disables analytics", () =>Effect.gen(function* () {- const capturedRequests: Array<RecordedBatchRequest> = [];const serverConfigLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {- prefix: "t3-telemetry-base-",+ prefix: "akeru-analytics-disabled-",});-- const telemetryLayer = AnalyticsService.layer.pipe(Layer.provideMerge(serverConfigLayer));- const configLayer = ConfigProvider.layer(- ConfigProvider.fromUnknown({- T3CODE_TELEMETRY_ENABLED: true,- T3CODE_POSTHOG_KEY: "phc_test_key",- T3CODE_POSTHOG_HOST: "http://localhost",- T3CODE_TELEMETRY_FLUSH_BATCH_SIZE: 20,- }),+ const analyticsLayer = makeLayers(serverConfigLayer).pipe(+ Layer.provide(+ ConfigProvider.layer(ConfigProvider.fromUnknown({ T3CODE_TELEMETRY_ENABLED: false })),+ ),);- const batchServerLayer = HttpServer.serve(- Effect.gen(function* () {- const request = yield* HttpServerRequest.HttpServerRequest;- if (request.method !== "POST") {- return HttpServerResponse.empty({ status: 404 });- }-- const payload = yield* request.json.pipe(- Effect.map((body) => body as RecordedBatchRequest["body"]),- Effect.orElseSucceed(() => null),- );- capturedRequests.push({ path: request.url, body: payload });+ yield* Effect.gen(function* () {+ const config = yield* ServerConfig.ServerConfig;+ const fs = yield* FileSystem.FileSystem;+ const analytics = yield* AnalyticsService.AnalyticsService;+ yield* fs.writeFileString(config.analyticsStatePath, "queued analytics");+ yield* fs.writeFileString(config.anonymousIdPath, "legacy identity");++ yield* analytics.flush;- return HttpServerResponse.jsonUnsafe({});- }),- );- const runtimeLayer = telemetryLayer.pipe(- Layer.provide(configLayer),- Layer.provideMerge(NodeHttpServer.layerTest),+ assert.isFalse(yield* fs.exists(config.analyticsStatePath));+ assert.isFalse(yield* fs.exists(config.anonymousIdPath));+ }).pipe(Effect.provide(analyticsLayer));+ }),+ );++ it.effect("deletes analytics state when no PostHog key is configured", () =>+ Effect.gen(function* () {+ const serverConfigLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {+ prefix: "akeru-analytics-no-key-",+ });+ const analyticsLayer = makeLayers(serverConfigLayer).pipe(+ Layer.provide(+ ConfigProvider.layer(ConfigProvider.fromUnknown({ T3CODE_TELEMETRY_ENABLED: true })),+ ),);yield* Effect.gen(function* () {- yield* Layer.launch(batchServerLayer).pipe(Effect.forkScoped);- const telemetryIdentifier = yield* getTelemetryIdentifier;- assert.equal(telemetryIdentifier !== null, true);+ const config = yield* ServerConfig.ServerConfig;+ const fs = yield* FileSystem.FileSystem;const analytics = yield* AnalyticsService.AnalyticsService;-- for (let index = 0; index < 45; index += 1) {- yield* analytics.record("test.flush.drain", { index });- }+ yield* fs.writeFileString(config.analyticsStatePath, "queued analytics");yield* analytics.flush;- }).pipe(Effect.provide(runtimeLayer));- const batchRequests = capturedRequests.filter(- (request): request is RecordedBatchRequest & { readonly body: RecordedBatchBody } =>- Array.isArray(request.body?.batch),- );- assert.equal(batchRequests.length, 3);- assert.equal(- batchRequests.every(- (request) => request.path.endsWith("/batch/") || request.path.endsWith("/batch"),+ assert.isFalse(yield* fs.exists(config.analyticsStatePath));+ }).pipe(Effect.provide(analyticsLayer));+ }),+ );++ it.effect("does not discard or overfill a full pending queue", () =>+ Effect.gen(function* () {+ const serverConfigLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {+ prefix: "akeru-analytics-full-",+ });+ const analyticsLayer = makeLayers(serverConfigLayer).pipe(+ Layer.provide(+ ConfigProvider.layer(+ ConfigProvider.fromUnknown({+ T3CODE_TELEMETRY_ENABLED: true,+ T3CODE_POSTHOG_KEY: "phc_test",+ }),+ ),),- true,- );- const deliveredIndexes = batchRequests.flatMap((request) =>- request.body.batch- .filter((event) => event.event === "test.flush.drain")- .map((event) => event.properties?.index)- .filter((index): index is number => typeof index === "number"),);- const sorted = deliveredIndexes.toSorted((a, b) => a - b);- assert.equal(sorted.length, 45);- assert.deepEqual(- sorted,- Array.from({ length: 45 }, (_, index) => index),- );- assert.equal(- batchRequests.every((request) =>- request.body.batch.every((event) => event.properties?.clientType === "cli-web-client"),- ),- true,+ yield* Effect.gen(function* () {+ const config = yield* ServerConfig.ServerConfig;+ const fs = yield* FileSystem.FileSystem;+ const analytics = yield* AnalyticsService.AnalyticsService;+ const cursorBucketStart = "2026-08-30T00:00:00.000Z";+ const deliveryDay = AnalyticsService.bucketStartAt(+ DateTime.toEpochMillis(yield* DateTime.now),+ ).slice(0, 10);+ yield* fs.writeFileString(+ config.analyticsStatePath,+ encodeJson({+ version: 1,+ installationId: pendingEvent.distinct_id,+ cursorBucketStart,+ deliveryDay,+ deliveredToday: 8,+ firstActiveInstallReported: true,+ pending: Array.from({ length: 256 }, () => pendingEvent),+ }),+ );++ yield* analytics.flush;+ const state = readState(yield* fs.readFileString(config.analyticsStatePath));+ assert.equal(state.pending.length, 256);+ assert.equal(state.cursorBucketStart, cursorBucketStart);+ }).pipe(Effect.provide(analyticsLayer));+ }),+ );++ it.effect("keeps provider account files outside the analytics identity path", () =>+ Effect.gen(function* () {+ const fs = yield* FileSystem.FileSystem;+ const source = yield* fs.readFileString(+ new URL("./AnalyticsService.ts", import.meta.url).pathname,);+ assert.notInclude(source, ".codex");+ assert.notInclude(source, ".claude");+ assert.notInclude(source, "auth.json");}),);});diff --git a/apps/server/src/telemetry/AnalyticsService.ts b/apps/server/src/telemetry/AnalyticsService.tsindex ce1d6f834..37126d291 100644--- a/apps/server/src/telemetry/AnalyticsService.ts+++ b/apps/server/src/telemetry/AnalyticsService.ts@@ -1,186 +1,527 @@-/**- * Anonymous PostHog telemetry service.- *- * Persists an installation-scoped anonymous identifier, buffers events in- * memory, and flushes batches over Effect's HTTP client.- *- * @module AnalyticsService- */+import * as NodeCrypto from "node:crypto";+import {+ USAGE_3H_COUNTER_KEYS,+ USAGE_3H_COUNTER_MAX,+ USAGE_BASE_COUNTER_KEYS,+ USAGE_PLUGIN_IDS,+ USAGE_TOOL_IDS,+ Usage3hEvent,+ decodeUsage3hEvent,+ type Usage3hEvent as Usage3hEventType,+ type UsageAnalyticsProvider,+ type UsageArchitecture,+ type UsageClientType,+ type UsageOperatingSystem,+ type UsageSandboxProvider,+} from "@t3tools/contracts";import { HostProcessArchitecture, HostProcessPlatform } from "@t3tools/shared/hostProcess";import * as Config from "effect/Config";import * as Context from "effect/Context";import * as DateTime from "effect/DateTime";import * as Effect from "effect/Effect";+import * as FileSystem from "effect/FileSystem";import * as Layer from "effect/Layer";import * as Option from "effect/Option";-import * as Ref from "effect/Ref";+import * as Path from "effect/Path";+import * as Schema from "effect/Schema";+import * as Semaphore from "effect/Semaphore";+import * as Stream from "effect/Stream";+import * as SqlClient from "effect/unstable/sql/SqlClient";import * as HttpClient from "effect/unstable/http/HttpClient";import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";import packageJson from "../../package.json" with { type: "json" };+import { writeFileStringAtomically } from "../atomicWrite.ts";import * as ServerConfig from "../config.ts";-import { getTelemetryIdentifier } from "./Identify.ts";+import * as ServerSettings from "../serverSettings.ts";-interface BufferedAnalyticsEvent {- readonly event: string;- readonly properties?: Readonly<Record<string, unknown>>;- readonly capturedAt: string;-}+const BUCKET_HOURS = 3;+const BUCKET_MS = BUCKET_HOURS * 60 * 60 * 1_000;+const MAX_PENDING_BUCKETS = 256;+const MAX_BUCKETS_PER_PASS = 8;+const MAX_BATCH_BYTES = 64 * 1_024;-const TelemetryEnvConfig = Config.all({- posthogKey: Config.string("T3CODE_POSTHOG_KEY").pipe(- Config.withDefault("phc_XOWci4oZP4VvLiEyrFqkFjP4CZn55mjYYBMREK5Wd6m"),+const AnalyticsState = Schema.Struct({+ version: Schema.Literal(1),+ installationId: Schema.String.check(Schema.isUUID()),+ cursorBucketStart: Schema.String.check(+ Schema.isPattern(/^\d{4}-\d{2}-\d{2}T(?:00|03|06|09|12|15|18|21):00:00\.000Z$/),),+ deliveryDay: Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/)),+ deliveredToday: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 8 })),+ firstActiveInstallReported: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),+ pending: Schema.Array(Usage3hEvent).check(Schema.isMaxLength(MAX_PENDING_BUCKETS)),+});+type AnalyticsState = typeof AnalyticsState.Type;++const decodeState = Schema.decodeUnknownSync(Schema.fromJsonString(AnalyticsState), {+ onExcessProperty: "error",+});+const encodeState = Schema.encodeSync(Schema.fromJsonString(AnalyticsState));+const encodeJson = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));++const TelemetryEnvConfig = Config.all({+ posthogKey: Config.option(Config.string("T3CODE_POSTHOG_KEY")),posthogHost: Config.string("T3CODE_POSTHOG_HOST").pipe(Config.withDefault("https://us.i.posthog.com"),),- enabled: Config.boolean("T3CODE_TELEMETRY_ENABLED").pipe(Config.withDefault(true)),- flushBatchSize: Config.number("T3CODE_TELEMETRY_FLUSH_BATCH_SIZE").pipe(Config.withDefault(20)),- maxBufferedEvents: Config.number("T3CODE_TELEMETRY_MAX_BUFFERED_EVENTS").pipe(- Config.withDefault(1_000),- ),- wslDistroName: Config.string("WSL_DISTRO_NAME").pipe(Config.option),+ enabled: Config.option(Config.boolean("T3CODE_TELEMETRY_ENABLED")),+ nodeEnvironment: Config.option(Config.string("NODE_ENV")),+ ci: Config.option(Config.boolean("CI")),});+interface BucketAggregateRow {+ readonly botsCreated: number;+ readonly botsDeleted: number;+ readonly botsRestored: number;+ readonly botsTotalCreated: number;+ readonly botsTotalDeleted: number;+ readonly botsTotalRestored: number;+ readonly userMessages: number;+ readonly botReplies: number;+ readonly failedTurns: number;+ readonly groupMessages: number;+ readonly approvalsRequested: number;+ readonly approvalsAccepted: number;+ readonly approvalsRejected: number;+ readonly clientSurfaces: string | null;+ readonly providers: string | null;+ readonly sandboxes: string | null;+}++interface TurnUsageRow {+ readonly provider: string | null;+ readonly sandbox: string | null;+ readonly count: number;+}++interface ToolUsageRow {+ readonly itemType: string | null;+ readonly provider: string | null;+ readonly count: number;+}++interface EnabledPluginRow {+ readonly pluginId: string;+}++export function bucketStartAt(timestamp: number): string {+ return DateTime.formatIso(DateTime.makeUnsafe(Math.floor(timestamp / BUCKET_MS) * BUCKET_MS));+}++function bucketEnd(bucketStart: string): string {+ return DateTime.formatIso(+ DateTime.add(DateTime.makeUnsafe(bucketStart), { hours: BUCKET_HOURS }),+ );+}++function clampCounter(value: number): number {+ return Math.min(USAGE_3H_COUNTER_MAX, Math.max(0, Math.floor(value)));+}++function collapse<T extends string>(+ encoded: string | null,+ allowed: ReadonlySet<string>,+ normalize: (value: string) => T,+ none: T,+ mixed: T,+): T {+ const values = new Set(+ (encoded ?? "")+ .split(",")+ .filter(Boolean)+ .map((value) => (allowed.has(value) ? normalize(value) : normalize("other"))),+ );+ if (values.size === 0) return none;+ if (values.size > 1) return mixed;+ return values.values().next().value ?? none;+}++const providerValues = new Set([+ "codex",+ "claude",+ "claudeagent",+ "cursor",+ "grok",+ "kimi",+ "opencode",+]);+function normalizeProvider(value: string): UsageAnalyticsProvider {+ if (value === "claudeagent") return "claude";+ if (value === "other") return "other";+ return providerValues.has(value) ? (value as UsageAnalyticsProvider) : "other";+}++const sandboxValues = new Set(["none", "local", "vercel", "akeru-cloud", "upstash"]);+function normalizeSandbox(value: string): UsageSandboxProvider {+ if (value === "other") return "other";+ return sandboxValues.has(value) ? (value as UsageSandboxProvider) : "other";+}++const clientValues = new Set(["web", "desktop", "mobile"]);+function normalizeClient(value: string): UsageClientType {+ if (value === "other") return "none";+ return clientValues.has(value) ? (value as UsageClientType) : "none";+}++function operatingSystem(value: string): UsageOperatingSystem {+ return value === "darwin" || value === "linux" || value === "win32" ? value : "other";+}++function architecture(value: string): UsageArchitecture {+ return value === "x64" || value === "arm64" || value === "arm" || value === "ia32"+ ? value+ : "other";+}++function insertId(installationId: string, start: string): string {+ return NodeCrypto.createHash("sha256").update(`${installationId}:${start}`).digest("hex");+}++function hasActivity(properties: Usage3hEventType["properties"]): boolean {+ return USAGE_3H_COUNTER_KEYS.some(+ (key) => key !== "bots_total" && !key.startsWith("plugin_enabled_") && properties[key] > 0,+ );+}+export class AnalyticsService extends Context.Service<AnalyticsService,{- /** Record an anonymous event for best-effort buffered delivery. */- readonly record: (- event: string,- properties?: Readonly<Record<string, unknown>>,- ) => Effect.Effect<void>;-- /** Flush all currently queued telemetry events. */+ /** Close ready buckets and attempt one bounded delivery batch. */readonly flush: Effect.Effect<void>;}>()("akeru-bot/telemetry/AnalyticsService") {- /** No-op layer for callers that intentionally disable telemetry. */static readonly layerTest = Layer.succeed(AnalyticsService,- AnalyticsService.of({- record: () => Effect.void,- flush: Effect.void,- }),+ AnalyticsService.of({ flush: Effect.void }),);}export const make = Effect.gen(function* () {- const telemetryConfig = yield* TelemetryEnvConfig;+ const environment = yield* TelemetryEnvConfig;const httpClient = yield* HttpClient.HttpClient;+ const fs = yield* FileSystem.FileSystem;+ const path = yield* Path.Path;+ const sql = yield* SqlClient.SqlClient;const serverConfig = yield* ServerConfig.ServerConfig;- const identifier = yield* getTelemetryIdentifier;- const bufferRef = yield* Ref.make<ReadonlyArray<BufferedAnalyticsEvent>>([]);- const clientType = serverConfig.mode === "desktop" ? "desktop-app" : "cli-web-client";+ const serverSettings = yield* ServerSettings.ServerSettingsService;const hostPlatform = yield* HostProcessPlatform;const hostArchitecture = yield* HostProcessArchitecture;+ const lock = yield* Semaphore.make(1);- const enqueueBufferedEvent = (event: string, properties?: Readonly<Record<string, unknown>>) =>- Effect.flatMap(DateTime.now, (now) =>- Ref.modify(bufferRef, (current) => {- const appended = [- ...current,- {- event,- ...(properties ? { properties } : {}),- capturedAt: DateTime.formatIso(now),- } satisfies BufferedAnalyticsEvent,- ];-- const next =- appended.length > telemetryConfig.maxBufferedEvents- ? appended.slice(appended.length - telemetryConfig.maxBufferedEvents)- : appended;-- return [- {- size: next.length,- dropped: next.length !== appended.length,- } as const,- next,- ] as const;- }),- );+ const isDevelopment =+ serverConfig.devUrl !== undefined ||+ ["development", "test"].includes(Option.getOrElse(environment.nodeEnvironment, () => ""));+ const defaultEnabled = !isDevelopment && !Option.getOrElse(environment.ci, () => false);+ const environmentEnabled = Option.getOrElse(environment.enabled, () => defaultEnabled);++ const removeAnalyticsState = Effect.gen(function* () {+ yield* fs.remove(serverConfig.analyticsStatePath, { force: true });+ yield* fs.remove(serverConfig.anonymousIdPath, { force: true });+ }).pipe(Effect.catch(() => Effect.void));- const sendBatch = Effect.fn("AnalyticsService.sendBatch")(function* (- events: ReadonlyArray<BufferedAnalyticsEvent>,- ) {- if (!telemetryConfig.enabled || !identifier) return;-- const payload = {- api_key: telemetryConfig.posthogKey,- batch: events.map((event) => ({- event: event.event,- distinct_id: identifier,- properties: {- ...event.properties,- $process_person_profile: false,- platform: hostPlatform,- wsl: Option.getOrUndefined(telemetryConfig.wslDistroName),- arch: hostArchitecture,- t3CodeVersion: packageJson.version,- clientType,- },- timestamp: event.capturedAt,- })),- };-- yield* HttpClientRequest.post(`${telemetryConfig.posthogHost}/batch/`).pipe(- HttpClientRequest.bodyJson(payload),- Effect.flatMap(httpClient.execute),- Effect.flatMap(HttpClientResponse.filterStatusOk),+ const writeState = (state: AnalyticsState) =>+ writeFileStringAtomically({+ filePath: serverConfig.analyticsStatePath,+ contents: encodeState(state),+ }).pipe(+ Effect.provideService(FileSystem.FileSystem, fs),+ Effect.provideService(Path.Path, path),);- });- const flush: AnalyticsService["Service"]["flush"] = Effect.gen(function* () {- while (true) {- const batch = yield* Ref.modify(bufferRef, (current) => {- if (current.length === 0) {- return [[] as ReadonlyArray<BufferedAnalyticsEvent>, current] as const;- }- const nextBatch = current.slice(0, telemetryConfig.flushBatchSize);- const remaining = current.slice(nextBatch.length);- return [nextBatch, remaining] as const;- });+ const loadState = (now: number) =>+ Effect.gen(function* () {+ // Migration is deletion-only. Never read or transform the inherited identity.+ yield* fs.remove(serverConfig.anonymousIdPath, { force: true });+ if (!(yield* fs.exists(serverConfig.analyticsStatePath))) {+ const fresh: AnalyticsState = {+ version: 1,+ installationId: NodeCrypto.randomUUID(),+ cursorBucketStart: bucketStartAt(now),+ deliveryDay: bucketStartAt(now).slice(0, 10),+ deliveredToday: 0,+ firstActiveInstallReported: false,+ pending: [],+ };+ yield* writeState(fresh);+ return fresh;+ }+ const encoded = yield* fs.readFileString(serverConfig.analyticsStatePath);+ return yield* Effect.sync(() => decodeState(encoded));+ });- if (batch.length === 0) {- return;+ const persistState = writeState;++ const readBucket = (start: string, end: string) =>+ Effect.gen(function* () {+ const [rows, turnUsage, toolUsage, enabledPlugins] = yield* Effect.all([+ sql<BucketAggregateRow>`+ SELECT+ COALESCE(SUM(CASE WHEN e.event_type = 'bot.created' THEN 1 ELSE 0 END), 0) AS "botsCreated",+ COALESCE(SUM(CASE WHEN e.event_type = 'bot.archived' THEN 1 ELSE 0 END), 0) AS "botsDeleted",+ COALESCE(SUM(CASE WHEN e.event_type = 'bot.restored' THEN 1 ELSE 0 END), 0) AS "botsRestored",+ (SELECT COUNT(*) FROM orchestration_events+ WHERE event_type = 'bot.created' AND occurred_at < ${end}+ AND COALESCE(json_extract(metadata_json, '$.importedHistory'), 0) <> 1) AS "botsTotalCreated",+ (SELECT COUNT(*) FROM orchestration_events+ WHERE event_type = 'bot.archived' AND occurred_at < ${end}+ AND COALESCE(json_extract(metadata_json, '$.importedHistory'), 0) <> 1) AS "botsTotalDeleted",+ (SELECT COUNT(*) FROM orchestration_events+ WHERE event_type = 'bot.restored' AND occurred_at < ${end}+ AND COALESCE(json_extract(metadata_json, '$.importedHistory'), 0) <> 1) AS "botsTotalRestored",+ COALESCE(SUM(CASE WHEN e.event_type = 'thread.message-sent'+ AND json_extract(e.payload_json, '$.role') = 'user' THEN 1 ELSE 0 END), 0) AS "userMessages",+ COALESCE(SUM(CASE WHEN e.event_type = 'thread.message-sent'+ AND json_extract(e.payload_json, '$.role') = 'assistant'+ AND json_extract(e.payload_json, '$.streaming') = 0 THEN 1 ELSE 0 END), 0) AS "botReplies",+ COUNT(DISTINCT CASE WHEN e.event_type = 'thread.activity-appended'+ AND json_extract(e.payload_json, '$.activity.tone') = 'error'+ AND json_extract(e.payload_json, '$.activity.turnId') IS NOT NULL+ THEN json_extract(e.payload_json, '$.activity.turnId') END) AS "failedTurns",+ COALESCE(SUM(CASE WHEN e.event_type = 'thread.message-sent'+ AND json_extract(e.payload_json, '$.role') = 'user'+ AND t.group_id IS NOT NULL THEN 1 ELSE 0 END), 0) AS "groupMessages",+ COALESCE(SUM(CASE WHEN e.event_type = 'thread.activity-appended'+ AND json_extract(e.payload_json, '$.activity.kind') = 'approval.requested'+ THEN 1 ELSE 0 END), 0) AS "approvalsRequested",+ COALESCE(SUM(CASE WHEN e.event_type = 'thread.approval-response-requested'+ AND json_extract(e.payload_json, '$.decision') IN ('accept', 'acceptForSession', 'acceptAlways')+ THEN 1 ELSE 0 END), 0) AS "approvalsAccepted",+ COALESCE(SUM(CASE WHEN e.event_type = 'thread.approval-response-requested'+ AND json_extract(e.payload_json, '$.decision') IN ('decline', 'cancel')+ THEN 1 ELSE 0 END), 0) AS "approvalsRejected",+ group_concat(DISTINCT json_extract(e.metadata_json, '$.origin.surface')) AS "clientSurfaces",+ group_concat(DISTINCT lower(json_extract(b.engine_json, '$.provider'))) AS "providers",+ group_concat(DISTINCT b.sandbox) AS "sandboxes"+ FROM orchestration_events e+ LEFT JOIN projection_threads t ON t.thread_id = e.stream_id+ LEFT JOIN projection_bots b ON b.bot_id = COALESCE(+ json_extract(e.payload_json, '$.respondingBotId'),+ t.responding_bot_id,+ t.bot_id,+ json_extract(e.payload_json, '$.botId')+ )+ WHERE e.occurred_at >= ${start}+ AND e.occurred_at < ${end}+ AND COALESCE(json_extract(e.metadata_json, '$.importedHistory'), 0) <> 1+ `,+ sql<TurnUsageRow>`+ SELECT lower(json_extract(b.engine_json, '$.provider')) AS "provider",+ b.sandbox AS "sandbox", COUNT(*) AS "count"+ FROM orchestration_events e+ LEFT JOIN projection_threads t ON t.thread_id = e.stream_id+ LEFT JOIN projection_bots b ON b.bot_id = COALESCE(+ json_extract(e.payload_json, '$.respondingBotId'),+ t.responding_bot_id,+ t.bot_id+ )+ WHERE e.event_type = 'thread.turn-start-requested'+ AND e.occurred_at >= ${start} AND e.occurred_at < ${end}+ AND COALESCE(json_extract(e.metadata_json, '$.importedHistory'), 0) <> 1+ GROUP BY "provider", "sandbox"+ `,+ sql<ToolUsageRow>`+ SELECT json_extract(e.payload_json, '$.activity.payload.itemType') AS "itemType",+ lower(json_extract(b.engine_json, '$.provider')) AS "provider",+ COUNT(*) AS "count"+ FROM orchestration_events e+ LEFT JOIN projection_turns turn+ ON turn.thread_id = e.stream_id+ AND turn.turn_id = json_extract(e.payload_json, '$.activity.turnId')+ LEFT JOIN projection_bots b ON b.bot_id = turn.responding_bot_id+ WHERE e.event_type = 'thread.activity-appended'+ AND json_extract(e.payload_json, '$.activity.kind') = 'tool.completed'+ AND e.occurred_at >= ${start} AND e.occurred_at < ${end}+ AND COALESCE(json_extract(e.metadata_json, '$.importedHistory'), 0) <> 1+ GROUP BY "itemType", "provider"+ `,+ sql<EnabledPluginRow>`+ SELECT substr(mcp_server_id, 9) AS "pluginId"+ FROM projection_mcp_servers+ WHERE enabled = 1 AND mcp_server_id LIKE 'builtin-%'+ `,+ ]);+ const row = rows[0];+ if (!row) return null;++ const capabilityCounters = Object.fromEntries(+ USAGE_3H_COUNTER_KEYS.slice(USAGE_BASE_COUNTER_KEYS.length).map((key) => [key, 0]),+ );+ for (const usage of turnUsage) {+ const provider = normalizeProvider(usage.provider ?? "other");+ capabilityCounters[`provider_turns_${provider}`] = clampCounter(+ (capabilityCounters[`provider_turns_${provider}`] ?? 0) + usage.count,+ );+ const sandbox = normalizeSandbox(usage.sandbox ?? "none").replaceAll("-", "_");+ capabilityCounters[`sandbox_turns_${sandbox}`] = clampCounter(+ (capabilityCounters[`sandbox_turns_${sandbox}`] ?? 0) + usage.count,+ );+ }+ for (const usage of toolUsage) {+ if (usage.itemType && USAGE_TOOL_IDS.includes(usage.itemType as never)) {+ capabilityCounters[`tool_calls_${usage.itemType}`] = clampCounter(+ (capabilityCounters[`tool_calls_${usage.itemType}`] ?? 0) + usage.count,+ );+ if (usage.itemType === "web_search") {+ const provider = normalizeProvider(usage.provider ?? "other");+ capabilityCounters[`browser_searches_${provider}`] = clampCounter(+ (capabilityCounters[`browser_searches_${provider}`] ?? 0) + usage.count,+ );+ }+ }+ }+ const enabledPluginIds = new Set(enabledPlugins.map((plugin) => plugin.pluginId));+ for (const pluginId of USAGE_PLUGIN_IDS) {+ capabilityCounters[`plugin_enabled_${pluginId}`] = Number(+ enabledPluginIds.has(pluginId.replaceAll("_", "-")),+ );}- yield* sendBatch(batch).pipe(- Effect.catch((error) =>- Ref.update(bufferRef, (current) => [...batch, ...current]).pipe(- Effect.flatMap(() => Effect.fail(error)),- ),+ const properties = {+ app_version: packageJson.version,+ operating_system: operatingSystem(hostPlatform),+ architecture: architecture(hostArchitecture),+ client_type: collapse(row.clientSurfaces, clientValues, normalizeClient, "none", "mixed"),+ provider: collapse(row.providers, providerValues, normalizeProvider, "none", "mixed"),+ sandbox_provider: collapse(row.sandboxes, sandboxValues, normalizeSandbox, "none", "mixed"),+ bucket_start: start,+ new_installations: 0,+ bots_created: clampCounter(row.botsCreated),+ bots_deleted: clampCounter(row.botsDeleted),+ bots_total: clampCounter(+ row.botsTotalCreated - row.botsTotalDeleted + row.botsTotalRestored,),- );- }- }).pipe(Effect.catch((cause) => Effect.logError("Failed to flush telemetry", { cause })));-- const record: AnalyticsService["Service"]["record"] = Effect.fn("AnalyticsService.record")(- function* (event, properties) {- if (!telemetryConfig.enabled || !identifier) return;-- const enqueueResult = yield* enqueueBufferedEvent(event, properties);- if (enqueueResult.dropped) {- yield* Effect.logDebug("analytics buffer full; dropping oldest event", {- size: enqueueResult.size,- event,+ user_messages: clampCounter(row.userMessages),+ bot_replies: clampCounter(row.botReplies),+ failed_turns: clampCounter(row.failedTurns),+ group_messages: clampCounter(row.groupMessages),+ external_messages: 0,+ voice_sessions: 0,+ browser_tasks: 0,+ routines_run: 0,+ routine_failures: 0,+ connector_calls: 0,+ connector_failures: 0,+ approvals_requested: clampCounter(row.approvalsRequested),+ approvals_accepted: clampCounter(row.approvalsAccepted),+ approvals_rejected: clampCounter(row.approvalsRejected),+ ...capabilityCounters,+ $process_person_profile: false,+ $geoip_disable: true,+ $ip: "0.0.0.0",+ $insert_id: "",+ } as Usage3hEventType["properties"];+ return {+ properties,+ changed: row.botsRestored > 0 || hasActivity(properties),+ };+ });++ const closeBuckets = (state: AnalyticsState, now: number) =>+ Effect.gen(function* () {+ let next = state;+ const currentStart = bucketStartAt(now);+ for (+ let count = 0;+ count < MAX_BUCKETS_PER_PASS &&+ next.cursorBucketStart < currentStart &&+ next.pending.length < MAX_PENDING_BUCKETS;+ count += 1+ ) {+ const start = next.cursorBucketStart;+ const end = bucketEnd(start);+ const aggregate = yield* readBucket(start, end);+ const changed = aggregate !== null && aggregate.changed;+ const pending = changed+ ? next.pending.concat(+ decodeUsage3hEvent({+ event: "usage_3h",+ distinct_id: next.installationId,+ properties: {+ ...aggregate.properties,+ new_installations: Number(!next.firstActiveInstallReported),+ $insert_id: insertId(next.installationId, start),+ },+ timestamp: end,+ }),+ )+ : next.pending;+ next = Object.assign({}, next, {+ cursorBucketStart: end,+ firstActiveInstallReported: next.firstActiveInstallReported || changed,+ pending,});+ yield* persistState(next);}- },+ return next;+ });++ const sendPending = (state: AnalyticsState, now: number) =>+ Effect.gen(function* () {+ const key = Option.getOrUndefined(environment.posthogKey);+ if (!key || state.pending.length === 0) return state;+ const deliveryDay = bucketStartAt(now).slice(0, 10);+ const deliveredToday = state.deliveryDay === deliveryDay ? state.deliveredToday : 0;+ const available = 8 - deliveredToday;+ if (available === 0) return state;+ const batch = state.pending+ .slice(0, Math.min(MAX_BUCKETS_PER_PASS, available))+ .map((event) => decodeUsage3hEvent(event));+ const body = { api_key: key, batch };+ if (encodeJson(body).length > MAX_BATCH_BYTES) return state;++ yield* HttpClientRequest.post(`${environment.posthogHost.replace(/\/$/, "")}/batch/`).pipe(+ HttpClientRequest.bodyJson(body),+ Effect.flatMap(httpClient.execute),+ Effect.flatMap(HttpClientResponse.filterStatusOk),+ );+ const next = {+ ...state,+ deliveryDay,+ deliveredToday: deliveredToday + batch.length,+ pending: state.pending.slice(batch.length),+ };+ yield* persistState(next);+ return next;+ });++ const runOnce = lock.withPermits(1)(+ Effect.gen(function* () {+ const settings = yield* serverSettings.getSettings;+ if (!settings.analyticsEnabled) {+ yield* removeAnalyticsState;+ return;+ }+ if (!environmentEnabled) {+ if (Option.isSome(environment.enabled)) yield* removeAnalyticsState;+ return;+ }+ if (Option.isNone(environment.posthogKey)) {+ yield* removeAnalyticsState;+ return;+ }++ const now = DateTime.toEpochMillis(yield* DateTime.now);+ const state = yield* loadState(now);+ const closed = yield* closeBuckets(state, now);+ yield* sendPending(closed, now);+ }),);- yield* Effect.forever(Effect.sleep(1000).pipe(Effect.flatMap(() => flush)), {- disableYield: true,- }).pipe(Effect.forkScoped);+ const flush = runOnce.pipe(+ Effect.catch(() => Effect.logWarning("Anonymous analytics pass failed")),+ );- yield* Effect.addFinalizer(() => flush);+ yield* Effect.forever(Effect.sleep("1 minute").pipe(Effect.andThen(flush))).pipe(+ Effect.forkScoped,+ );+ yield* Stream.runForEach(serverSettings.streamChanges, (settings) =>+ settings.analyticsEnabled ? Effect.void : lock.withPermits(1)(removeAnalyticsState),+ ).pipe(Effect.forkScoped);- return AnalyticsService.of({ record, flush });+ return AnalyticsService.of({ flush });});export const layer = Layer.effect(AnalyticsService, make);-export const layerTest = AnalyticsService.layerTest;diff --git a/apps/server/src/telemetry/Identify.test.ts b/apps/server/src/telemetry/Identify.test.tsdeleted file mode 100644index ab1518217..000000000--- a/apps/server/src/telemetry/Identify.test.ts+++ /dev/null@@ -1,172 +0,0 @@-import * as NodeCrypto from "node:crypto";-import * as NodeServices from "@effect/platform-node/NodeServices";-import { assert, it } from "@effect/vitest";-import * as Effect from "effect/Effect";-import * as FileSystem from "effect/FileSystem";-import * as Layer from "effect/Layer";-import * as Logger from "effect/Logger";-import * as Path from "effect/Path";-import * as References from "effect/References";--import * as ServerConfig from "../config.ts";-import * as Identify from "./Identify.ts";--interface CapturedLog {- readonly message: unknown;- readonly annotations: Readonly<Record<string, unknown>>;-}--const sha256 = (value: string) =>- NodeCrypto.createHash("sha256").update(value, "utf8").digest("hex");--const makeCaptureLogger = (logs: CapturedLog[]) =>- Logger.make(({ fiber, message }) => {- logs.push({- message,- annotations: fiber.getRef(References.CurrentLogAnnotations),- });- });--const findIdentityLog = (- logs: ReadonlyArray<CapturedLog>,- source: Identify.TelemetryIdentitySource,- errorTag: string,-) => logs.find((log) => log.annotations.source === source && log.annotations.errorTag === errorTag);--it("preserves exact telemetry identity causes without deriving messages from them", () => {- const decodeCause = new Error("private nested decode details");- const decodeError = new Identify.TelemetryIdentityDecodeError({- source: "codex",- filePath: "/tmp/auth.json",- cause: decodeCause,- });- const readCause = new Error("private nested read details");- const readError = new Identify.TelemetryIdentityReadError({- source: "anonymous",- filePath: "/tmp/anonymous-id",- cause: readCause,- });-- assert.strictEqual(decodeError.cause, decodeCause);- assert.strictEqual(readError.cause, readCause);- assert.notInclude(decodeError.message, decodeCause.message);- assert.notInclude(readError.message, readCause.message);-});--it.layer(NodeServices.layer)("telemetry identity", (it) => {- it.effect("uses the persisted anonymous id when provider identities are absent", () =>- Effect.gen(function* () {- const config = yield* ServerConfig.ServerConfig;- const fileSystem = yield* FileSystem.FileSystem;- const path = yield* Path.Path;- const anonymousId = "persisted-anonymous-id";-- yield* fileSystem.writeFileString(config.anonymousIdPath, anonymousId);-- const identifier = yield* Identify.getTelemetryIdentifierForHome(- path.join(config.baseDir, "home"),- );-- assert.equal(identifier, sha256(anonymousId));- }).pipe(- Effect.provide(- ServerConfig.layerTest(process.cwd(), {- prefix: "t3-telemetry-identify-anonymous-",- }),- ),- ),- );-- it.effect("logs structured decode context and falls back from malformed Codex auth", () => {- const logs: CapturedLog[] = [];- const logger = makeCaptureLogger(logs);-- return Effect.gen(function* () {- const config = yield* ServerConfig.ServerConfig;- const fileSystem = yield* FileSystem.FileSystem;- const path = yield* Path.Path;- const homeDirectory = path.join(config.baseDir, "home");- const codexAuthPath = path.join(homeDirectory, ".codex", "auth.json");- const anonymousId = "decode-fallback-anonymous-id";- const privateAccessToken = "private-codex-access-token";-- yield* fileSystem.makeDirectory(path.dirname(codexAuthPath), { recursive: true });- yield* fileSystem.writeFileString(- codexAuthPath,- `{"tokens":{"access_token":"${privateAccessToken}"}}`,- );- yield* fileSystem.writeFileString(config.anonymousIdPath, anonymousId);-- const identifier = yield* Identify.getTelemetryIdentifierForHome(homeDirectory);-- assert.equal(identifier, sha256(anonymousId));- const decodeLog = findIdentityLog(logs, "codex", "TelemetryIdentityDecodeError");- assert.isDefined(decodeLog);- assert.equal(- decodeLog?.message,- `Failed to decode codex telemetry identity at '${codexAuthPath}'.`,- );-- assert.equal(decodeLog?.annotations.filePath, codexAuthPath);- assert.equal(decodeLog?.annotations.causeKind, "schema");- assert.notProperty(decodeLog?.annotations ?? {}, "cause");- const errorStack = decodeLog?.annotations.errorStack;- assert.isString(errorStack);- assert.include(errorStack, "Failed to decode codex telemetry identity");- const annotations = Object.values(decodeLog?.annotations ?? {})- .map(String)- .join("\n");- assert.notInclude(annotations, privateAccessToken);- }).pipe(- Effect.provide(- Layer.merge(- ServerConfig.layerTest(process.cwd(), {- prefix: "t3-telemetry-identify-decode-",- }),- Logger.layer([logger], { mergeWithExisting: false }),- ),- ),- );- });-- it.effect("does not overwrite the anonymous id path after a non-NotFound read failure", () => {- const logs: CapturedLog[] = [];- const logger = makeCaptureLogger(logs);-- return Effect.gen(function* () {- const config = yield* ServerConfig.ServerConfig;- const fileSystem = yield* FileSystem.FileSystem;- const path = yield* Path.Path;- const homeDirectory = path.join(config.baseDir, "home");-- yield* fileSystem.makeDirectory(config.anonymousIdPath);-- const identifier = yield* Identify.getTelemetryIdentifierForHome(homeDirectory);-- assert.isNull(identifier);- assert.deepEqual(yield* fileSystem.readDirectory(config.anonymousIdPath), []);-- const readLog = findIdentityLog(logs, "anonymous", "TelemetryIdentityReadError");- assert.isDefined(readLog);- assert.equal(readLog?.annotations.filePath, config.anonymousIdPath);- assert.equal(readLog?.annotations.causeKind, "platform");- assert.notEqual(readLog?.annotations.platformReason, "NotFound");- assert.notProperty(readLog?.annotations ?? {}, "cause");- const errorStack = readLog?.annotations.errorStack;- assert.isString(errorStack);- assert.include(errorStack, "Failed to read anonymous telemetry identity");- assert.isUndefined(- findIdentityLog(logs, "anonymous", "TelemetryAnonymousIdPersistenceError"),- );- }).pipe(- Effect.provide(- Layer.merge(- ServerConfig.layerTest(process.cwd(), {- prefix: "t3-telemetry-identify-read-",- }),- Logger.layer([logger], { mergeWithExisting: false }),- ),- ),- );- });-});diff --git a/apps/server/src/telemetry/Identify.ts b/apps/server/src/telemetry/Identify.tsdeleted file mode 100644index b6c3d0066..000000000--- a/apps/server/src/telemetry/Identify.ts+++ /dev/null@@ -1,303 +0,0 @@-import * as NodeOS from "node:os";-import * as Crypto from "effect/Crypto";-import * as Effect from "effect/Effect";-import * as Encoding from "effect/Encoding";-import * as FileSystem from "effect/FileSystem";-import * as Option from "effect/Option";-import * as Path from "effect/Path";-import * as PlatformError from "effect/PlatformError";-import * as Schema from "effect/Schema";--import * as ServerConfig from "../config.ts";--const CodexAuthJsonSchema = Schema.Struct({- tokens: Schema.Struct({- account_id: Schema.String,- }),-});--const ClaudeJsonSchema = Schema.Struct({- userID: Schema.String,-});--export const TelemetryIdentitySource = Schema.Literals(["codex", "claude", "anonymous"]);-export type TelemetryIdentitySource = typeof TelemetryIdentitySource.Type;--export class TelemetryIdentityReadError extends Schema.TaggedErrorClass<TelemetryIdentityReadError>()(- "TelemetryIdentityReadError",- {- source: TelemetryIdentitySource,- filePath: Schema.String,- cause: Schema.Defect(),- },-) {- override get message(): string {- return `Failed to read ${this.source} telemetry identity at '${this.filePath}'.`;- }-}--export class TelemetryIdentityDecodeError extends Schema.TaggedErrorClass<TelemetryIdentityDecodeError>()(- "TelemetryIdentityDecodeError",- {- source: Schema.Literals(["codex", "claude"]),- filePath: Schema.String,- cause: Schema.Defect(),- },-) {- override get message(): string {- return `Failed to decode ${this.source} telemetry identity at '${this.filePath}'.`;- }-}--export class TelemetryAnonymousIdGenerationError extends Schema.TaggedErrorClass<TelemetryAnonymousIdGenerationError>()(- "TelemetryAnonymousIdGenerationError",- {- source: Schema.Literal("anonymous"),- filePath: Schema.String,- cause: Schema.Defect(),- },-) {- override get message(): string {- return `Failed to generate anonymous telemetry identity for '${this.filePath}'.`;- }-}--export class TelemetryAnonymousIdPersistenceError extends Schema.TaggedErrorClass<TelemetryAnonymousIdPersistenceError>()(- "TelemetryAnonymousIdPersistenceError",- {- source: Schema.Literal("anonymous"),- filePath: Schema.String,- cause: Schema.Defect(),- },-) {- override get message(): string {- return `Failed to persist anonymous telemetry identity at '${this.filePath}'.`;- }-}--export class TelemetryIdentityHashError extends Schema.TaggedErrorClass<TelemetryIdentityHashError>()(- "TelemetryIdentityHashError",- {- source: TelemetryIdentitySource,- algorithm: Schema.Literal("SHA-256"),- cause: Schema.Defect(),- },-) {- override get message(): string {- return `Failed to hash ${this.source} telemetry identity with ${this.algorithm}.`;- }-}--type TelemetryIdentityError =- | TelemetryIdentityReadError- | TelemetryIdentityDecodeError- | TelemetryAnonymousIdGenerationError- | TelemetryAnonymousIdPersistenceError- | TelemetryIdentityHashError;--const decodeCodexAuthJson = Schema.decodeEffect(Schema.fromJsonString(CodexAuthJsonSchema));-const decodeClaudeJson = Schema.decodeEffect(Schema.fromJsonString(ClaudeJsonSchema));--function isNotFoundError(error: PlatformError.PlatformError): boolean {- return error.reason._tag === "NotFound";-}--const getTelemetryIdentityCauseAnnotations = (cause: unknown) => {- if (cause instanceof PlatformError.PlatformError) {- return {- causeKind: "platform",- platformReason: cause.reason._tag,- };- }- if (cause instanceof Schema.SchemaError) {- return { causeKind: "schema" };- }- return { causeKind: "other" };-};--const logTelemetryIdentityError = (error: TelemetryIdentityError) =>- Effect.logWarning(error.message).pipe(- Effect.annotateLogs({- errorTag: error._tag,- source: error.source,- ...("filePath" in error ? { filePath: error.filePath } : {}),- ...getTelemetryIdentityCauseAnnotations(error.cause),- ...(error.stack === undefined ? {} : { errorStack: error.stack }),- }),- );--const readIdentityFile = (- fileSystem: FileSystem.FileSystem,- source: TelemetryIdentitySource,- filePath: string,-) =>- fileSystem.readFileString(filePath).pipe(- Effect.map(Option.some),- Effect.catchTags({- PlatformError: (cause) =>- isNotFoundError(cause)- ? Effect.succeed(Option.none<string>())- : Effect.fail(- new TelemetryIdentityReadError({- source,- filePath,- cause,- }),- ),- }),- );--const hash = (source: TelemetryIdentitySource, value: string) =>- Crypto.Crypto.pipe(- Effect.flatMap((crypto) => crypto.digest("SHA-256", new TextEncoder().encode(value))),- Effect.map(Encoding.encodeHex),- Effect.mapError(- (cause) =>- new TelemetryIdentityHashError({- source,- algorithm: "SHA-256",- cause,- }),- ),- );--const getCodexAccountId = Effect.fn("TelemetryIdentity.getCodexAccountId")(function* (- homeDirectory: string,-) {- const fileSystem = yield* FileSystem.FileSystem;- const path = yield* Path.Path;-- const authJsonPath = path.join(homeDirectory, ".codex", "auth.json");- const encoded = yield* readIdentityFile(fileSystem, "codex", authJsonPath);- if (Option.isNone(encoded)) {- return Option.none<string>();- }- const authJson = yield* decodeCodexAuthJson(encoded.value).pipe(- Effect.mapError(- (cause) =>- new TelemetryIdentityDecodeError({- source: "codex",- filePath: authJsonPath,- cause,- }),- ),- );-- return Option.some(authJson.tokens.account_id);-});--const getClaudeUserId = Effect.fn("TelemetryIdentity.getClaudeUserId")(function* (- homeDirectory: string,-) {- const fileSystem = yield* FileSystem.FileSystem;- const path = yield* Path.Path;-- const claudeJsonPath = path.join(homeDirectory, ".claude.json");- const encoded = yield* readIdentityFile(fileSystem, "claude", claudeJsonPath);- if (Option.isNone(encoded)) {- return Option.none<string>();- }- const claudeJson = yield* decodeClaudeJson(encoded.value).pipe(- Effect.mapError(- (cause) =>- new TelemetryIdentityDecodeError({- source: "claude",- filePath: claudeJsonPath,- cause,- }),- ),- );-- return Option.some(claudeJson.userID);-});--const upsertAnonymousId = Effect.gen(function* () {- const fileSystem = yield* FileSystem.FileSystem;- const { anonymousIdPath } = yield* ServerConfig.ServerConfig;-- const existing = yield* readIdentityFile(fileSystem, "anonymous", anonymousIdPath);- if (Option.isSome(existing)) {- return existing.value;- }-- const anonymousId = yield* Crypto.Crypto.pipe(- Effect.flatMap((crypto) => crypto.randomUUIDv4),- Effect.mapError(- (cause) =>- new TelemetryAnonymousIdGenerationError({- source: "anonymous",- filePath: anonymousIdPath,- cause,- }),- ),- );- yield* fileSystem.writeFileString(anonymousIdPath, anonymousId).pipe(- Effect.mapError(- (cause) =>- new TelemetryAnonymousIdPersistenceError({- source: "anonymous",- filePath: anonymousIdPath,- cause,- }),- ),- );-- return anonymousId;-});--/**- * getTelemetryIdentifier - Users are "identified" by finding the first match of the following, then hashing the value.- * 1. ~/.codex/auth.json tokens.account_id- * 2. ~/.claude.json userID- * 3. ~/.t3/telemetry/anonymous-id- */-export const getTelemetryIdentifierForHome = Effect.fn("getTelemetryIdentifierForHome")(- function* (homeDirectory: string) {- const codexAccountId = yield* getCodexAccountId(homeDirectory).pipe(- Effect.catchTags({- TelemetryIdentityReadError: (error) =>- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),- TelemetryIdentityDecodeError: (error) =>- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),- }),- );- if (Option.isSome(codexAccountId)) {- return yield* hash("codex", codexAccountId.value);- }-- const claudeUserId = yield* getClaudeUserId(homeDirectory).pipe(- Effect.catchTags({- TelemetryIdentityReadError: (error) =>- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),- TelemetryIdentityDecodeError: (error) =>- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),- }),- );- if (Option.isSome(claudeUserId)) {- return yield* hash("claude", claudeUserId.value);- }-- const anonymousId = yield* upsertAnonymousId.pipe(- Effect.map(Option.some),- Effect.catchTags({- TelemetryIdentityReadError: (error) =>- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),- TelemetryAnonymousIdGenerationError: (error) =>- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),- TelemetryAnonymousIdPersistenceError: (error) =>- logTelemetryIdentityError(error).pipe(Effect.as(Option.none<string>())),- }),- );- if (Option.isSome(anonymousId)) {- return yield* hash("anonymous", anonymousId.value);- }-- return null;- },- Effect.tapError(logTelemetryIdentityError),- Effect.orElseSucceed(() => null),-);--export const getTelemetryIdentifier = Effect.suspend(() =>- getTelemetryIdentifierForHome(NodeOS.homedir()),-);diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.tsindex 84e82473a..b9db38eca 100644--- a/apps/server/src/ws.ts+++ b/apps/server/src/ws.ts@@ -142,7 +142,6 @@ import { requiredScopeForRpcMethod } from "./auth/RpcAuthorization.ts";import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";import * as ResourceTelemetry from "./resourceTelemetry/ResourceTelemetry.ts";-import * as AnalyticsService from "./telemetry/AnalyticsService.ts";import { BotUsageLedger } from "./usage/BotUsageLedger.ts";import * as UsageService from "./usage/UsageService.ts";import * as Portability from "./portability.ts";@@ -448,7 +447,6 @@ function toAuthAccessStreamEvent(const isClientSurface = Schema.is(ClientSurface);const MAX_CLIENT_APP_VERSION_LENGTH = 64;-const MAX_CLIENT_DEVICE_MODEL_LENGTH = 80;// Optional client identity announced on the /ws upgrade URL next to wsTicket.// Lenient by design: absent or malformed values degrade to {} so a connection@@ -470,33 +468,6 @@ function readClientConnectionOrigin(};}-const clientOriginAnalyticsProps = (origin: OrchestrationClientOrigin) => ({- ...(origin.surface !== undefined ? { surface: origin.surface } : {}),- ...(origin.appVersion !== undefined ? { appVersion: origin.appVersion } : {}),-});--function readMobileDeviceAnalyticsProps(request: HttpServerRequest.HttpServerRequest) {- const url = HttpServerRequest.toURL(request);- if (Option.isNone(url) || url.value.searchParams.get("clientSurface") !== "mobile") {- return {};- }-- const os = url.value.searchParams.get("clientOs");- const rawOsMajorVersion = url.value.searchParams.get("clientOsMajorVersion") ?? "";- const osMajorVersion = Number(rawOsMajorVersion);- const deviceModel = url.value.searchParams.get("clientDeviceModel")?.trim() ?? "";-- return {- ...(os === "iOS" || os === "Android" ? { os } : {}),- ...(rawOsMajorVersion !== "" && Number.isInteger(osMajorVersion) && osMajorVersion > 0- ? { osMajorVersion }- : {}),- ...(deviceModel !== "" && deviceModel.length <= MAX_CLIENT_DEVICE_MODEL_LENGTH- ? { deviceModel }- : {}),- };-}-const makeWsRpcLayer = (currentSession: EnvironmentAuth.AuthenticatedSession,clientOrigin: OrchestrationClientOrigin,@@ -515,7 +486,6 @@ const makeWsRpcLayer = (const entityMemoryRepository = yield* Effect.serviceOption(EntityMemoryRepository);const memoryCandidates = yield* Effect.serviceOption(MemoryCandidateRepository);const orchestrationEngine = yield* OrchestrationEngine.OrchestrationEngineService;- const analytics = yield* AnalyticsService.AnalyticsService;// Every command dispatched on this connection carries the connecting// client's origin, including server-generated bootstrap sub-commands:// the client's request caused them.@@ -528,22 +498,6 @@ const makeWsRpcLayer = (command,hasClientOrigin ? { origin: clientOrigin } : undefined,);- const originProps = clientOriginAnalyticsProps(clientOrigin);- const recordClientCommandAnalytics = (command: OrchestrationCommand) => {- switch (command.type) {- case "thread.create":- return analytics.record("client.thread.started", originProps);- case "thread.turn.start":- return command.bootstrap?.createThread- ? Effect.andThen(- analytics.record("client.thread.started", originProps),- analytics.record("client.turn.requested", originProps),- )- : analytics.record("client.turn.requested", originProps);- default:- return Effect.void;- }- };const checkpointDiffQuery = yield* CheckpointDiffQuery.CheckpointDiffQuery;const keybindings = yield* Keybindings.Keybindings;const externalLauncher = yield* ExternalLauncher.ExternalLauncher;@@ -1534,7 +1488,6 @@ const makeWsRpcLayer = (const result = yield* dispatchNormalizedCommand(normalizedCommand).pipe(Effect.tapError(() => cleanupFailedUploadedAttachments(command, normalizedCommand)),);- yield* recordClientCommandAnalytics(normalizedCommand);if (parkingCommand) {const parkingKind = parkingCommand.type === "thread.archive" ? "archive" : "settle";if (shouldStopSessionAfterCommand) {@@ -3064,7 +3017,6 @@ export const websocketRpcRouteLayer = Layer.unwrap(const request = yield* HttpServerRequest.HttpServerRequest;const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;const sessions = yield* SessionStore.SessionStore;- const analytics = yield* AnalyticsService.AnalyticsService;const session = yield* serverAuth.authenticateWebSocketUpgrade(request).pipe(Effect.catchIf(EnvironmentAuth.isServerAuthCredentialError, (error) =>failEnvironmentAuthInvalid(EnvironmentAuth.serverAuthCredentialReason(error)),@@ -3075,10 +3027,6 @@ export const websocketRpcRouteLayer = Layer.unwrap();const clientOrigin = readClientConnectionOrigin(request);yield* sessions.recordClientConnection(session.sessionId, clientOrigin);- yield* analytics.record("client.connected", {- ...clientOriginAnalyticsProps(clientOrigin),- ...readMobileDeviceAnalyticsProps(request),- });const rpcWebSocketHttpEffect = yield* RpcServer.toHttpEffectWebsocket(WsRpcGroup, {disableTracing: true,}).pipe(diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsxindex e4c76909e..fde93346f 100644--- a/apps/web/src/components/settings/SettingsPanels.tsx+++ b/apps/web/src/components/settings/SettingsPanels.tsx@@ -2665,6 +2665,17 @@ export function GeneralSettingsPanel() {description="Current version of the application."/>)}+ <SettingsRow+ {...searchableSetting("analytics")}+ description="Share anonymous usage data to help improve Akeru Bot."+ control={+ <Switch+ aria-label="Analytics"+ checked={settings.analyticsEnabled}+ onCheckedChange={(analyticsEnabled) => updateSettings({ analyticsEnabled })}+ />+ }+ /><SettingsRowtitle="Product feedback"control={diff --git a/apps/web/src/components/settings/settingsSearch.test.ts b/apps/web/src/components/settings/settingsSearch.test.tsindex 1eef5a690..e7e866e7c 100644--- a/apps/web/src/components/settings/settingsSearch.test.ts+++ b/apps/web/src/components/settings/settingsSearch.test.ts@@ -86,6 +86,13 @@ describe("searchSettings", () => {});});+ it("routes analytics to General settings", () => {+ expect(searchSettings("analytics")[0]).toMatchObject({+ id: "analytics",+ to: "/settings/general",+ });+ });+it("routes appearance settings to their current section", () => {expect(searchSettings("theme")[0]).toMatchObject({id: "theme",diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.tsindex 89062f972..b68738de1 100644--- a/apps/web/src/components/settings/settingsSearch.ts+++ b/apps/web/src/components/settings/settingsSearch.ts@@ -215,6 +215,11 @@ export const SETTINGS_SEARCH_ITEMS = [title: "Data portability",to: "/settings/general",},+ {+ id: "analytics",+ title: "Analytics",+ to: "/settings/general",+ },{id: "diagnostics",title: "Diagnostics",diff --git a/docs/README.md b/docs/README.mdindex 370a9b27b..64cccc723 100644--- a/docs/README.md+++ b/docs/README.md@@ -9,6 +9,7 @@- [Sending product feedback](./user/product-feedback.md)- [Plugins](./user/plugins.md)- [Review usage](./user/usage.md)+- [Anonymous usage analytics](./user/analytics.md)- [Customize a project icon](./user/project-settings.md)- [Mobile appearance](./user/mobile-appearance.md)- [Remote access](./user/remote-access.md)@@ -36,6 +37,7 @@ policy in [CONTRIBUTING.md](../CONTRIBUTING.md); agent rules in [AGENTS.md](../A- [Remote environments](./internals/remote.md)- [Server updates](./internals/server-updates.md)- [Resource telemetry](./internals/resource-telemetry.md)+- [Usage analytics](./internals/usage-analytics.md)- [Environment auth](./internals/environment-auth.md)- [T3 Connect](./internals/t3-connect.md)- [CI gates](./internals/ci.md)diff --git a/docs/internals/usage-analytics.md b/docs/internals/usage-analytics.mdnew file mode 100644index 000000000..8c4b20119--- /dev/null+++ b/docs/internals/usage-analytics.md@@ -0,0 +1,103 @@+# Usage analytics++> For maintainers. Using Akeru Bot? See [Anonymous usage analytics](../user/analytics.md).++Akeru Bot sends one PostHog event named `usage_3h` for each non-empty, closed+three-hour UTC bucket. The default destination is+`https://us.i.posthog.com/batch/`. `T3CODE_POSTHOG_HOST` changes the host and keeps+the `/batch/` path.++Packaged production builds enable analytics by default. Development and CI disable+it by default. `T3CODE_TELEMETRY_ENABLED` overrides that default for packaged,+headless, development, and CI runs.++## Payload contract++The event has 18 base counters:++- `new_installations`+- `bots_created`+- `bots_deleted`+- `bots_total`+- `user_messages`+- `bot_replies`+- `failed_turns`+- `group_messages`+- `external_messages`+- `voice_sessions`+- `browser_tasks`+- `routines_run`+- `routine_failures`+- `connector_calls`+- `connector_failures`+- `approvals_requested`+- `approvals_accepted`+- `approvals_rejected`++The schema bounds every counter. Analytics code must not add arbitrary counters or+properties.++The same fixed schema has counters for provider turns, sandbox turns, completed tool+categories, provider-native web searches by built-in adapter, and enabled public+catalog plugins. Plugin counters use reviewed catalog slugs. Unknown and custom MCP+server names, IDs, commands, arguments, and URLs never enter the event.++The server derives bots, messages, replies, failed turns, groups, approvals, provider+turns, sandbox turns, completed tool categories, and provider-native web searches+from durable orchestration events. It reads enabled catalog plugins from the local MCP+projection. External message, voice, sandbox browser, routine, and connector counters+remain zero until those features have a durable local count source.++`new_installations` is `1` in the first non-empty bucket for a new analytics UUID and+`0` afterward. It measures first active use, not a download or a person. It does not+make an otherwise empty bucket eligible to send.++The only allowed dimensions are:++- `app_version`+- `operating_system`+- `architecture`+- `client_type`+- `provider`+- `sandbox_provider`+- `bucket_start`++`bucket_start` is the UTC start time of the three-hour bucket. Empty buckets advance+the local cursor. Akeru Bot does not queue or send them.++## Identity and privacy boundary++The server creates a random analytics-only UUID. It does not read Codex, Claude, or+other provider authentication files. It does not derive the UUID from an account or+another Akeru Bot record.++The payload must never contain prompts, replies, model output, names, bot IDs,+thread IDs, workspace IDs, group IDs, account IDs, URLs, paths, recipients, memory,+connector payloads, tokens, credentials, screenshots, stack traces, error strings,+files, or arbitrary properties. It must not collect provider auth files, personal+information, user content, connector data, or IP addresses.++## Local state and delivery++The server keeps the open bucket and closed buckets that still need delivery in+local analytics state. It retains at most 256 closed buckets. If that limit is full,+the server stops closing buckets. It does not discard an older report to make room.++The server delivers at most eight closed buckets per UTC day. Each delivery attempt+also sends at most eight buckets. The server removes a bucket only after PostHog+returns a successful response. Failed sends stay local for a later retry.++Each event has a deterministic PostHog `$insert_id`. It is the lowercase SHA-256+hex digest of the random analytics UUID and `bucket_start`. PostHog can therefore+deduplicate a retry after an uncertain response.++## User control++The server setting `analyticsEnabled` is available as **Analytics** in+**Settings → General**. Turning it off immediately stops collection and deletes the+random analytics UUID, open bucket, pending buckets, and legacy analytics ID file.+The disabled setting persists. Turning analytics on later creates a new random UUID+and starts a new bucket.++This analytics path is separate from [resource telemetry](./resource-telemetry.md).+Resource telemetry supports local diagnostics and does not enter `usage_3h`.diff --git a/docs/user/analytics.md b/docs/user/analytics.mdnew file mode 100644index 000000000..2d66fd240--- /dev/null+++ b/docs/user/analytics.md@@ -0,0 +1,30 @@+# Anonymous usage analytics++Akeru Bot sends anonymous usage totals from packaged production builds. Development+and CI runs do not send analytics unless a maintainer enables them.++Each report covers one three-hour UTC period. It contains counts for bots, messages,+bot replies, failed turns, groups, approval decisions, provider turns, sandbox turns,+completed tool categories, and provider-native web searches. It also records which+public catalog plugins are enabled. Custom plugin names and MCP server details never+leave the installation.++The first report with activity marks the analytics installation as new. This supports+an anonymous new-active-install trend. It does not identify a person or count a+download that never runs.+Reserved counters for external messages, voice, browser tasks, routines, and+connectors stay at zero until those features have a durable local count source.++Akeru Bot uses a random UUID only for analytics. It does not read provider sign-in+files or use an account ID. Reports do not contain personal information, user+content, connector data, IP addresses, prompts, replies, model output, personal IDs,+URLs, paths, recipients, memory, payloads, tokens, credentials, screenshots, stack+traces, error text, files, or custom properties.++Turn off **Analytics** in **Settings → General** to stop collection. Akeru Bot then+deletes the analytics UUID, the current period, all reports waiting to send, and the+legacy analytics ID file. The setting stays off.++Resource diagnostics are separate. [Local resource telemetry](../internals/resource-telemetry.md)+measures processes and host resources for the diagnostics interface. It does not+send those measurements as anonymous usage analytics.diff --git a/packages/contracts/src/analytics.test.ts b/packages/contracts/src/analytics.test.tsnew file mode 100644index 000000000..15d26b0bf--- /dev/null+++ b/packages/contracts/src/analytics.test.ts@@ -0,0 +1,112 @@+import { describe, expect, it } from "vite-plus/test";++import {+ USAGE_3H_COUNTER_KEYS,+ USAGE_3H_COUNTER_MAX,+ USAGE_BASE_COUNTER_KEYS,+ decodeUsage3hEvent,+} from "./analytics.ts";++const event = {+ event: "usage_3h",+ distinct_id: "0f64da24-2c54-4d2a-9d68-f117c4e78e01",+ properties: {+ app_version: "1.2.3-beta.1+build.4",+ operating_system: "darwin",+ architecture: "arm64",+ client_type: "desktop",+ provider: "mixed",+ sandbox_provider: "local",+ bucket_start: "2026-08-31T18:00:00.000Z",+ new_installations: 1,+ bots_created: 1,+ bots_deleted: 0,+ bots_total: 3,+ user_messages: 2,+ bot_replies: 2,+ failed_turns: 0,+ group_messages: 0,+ external_messages: 0,+ voice_sessions: 0,+ browser_tasks: 0,+ routines_run: 0,+ routine_failures: 0,+ connector_calls: 0,+ connector_failures: 0,+ approvals_requested: 1,+ approvals_accepted: 1,+ approvals_rejected: 0,+ ...Object.fromEntries(+ USAGE_3H_COUNTER_KEYS.slice(USAGE_BASE_COUNTER_KEYS.length).map((key) => [key, 0]),+ ),+ $process_person_profile: false,+ $geoip_disable: true,+ $ip: "0.0.0.0",+ $insert_id: "a".repeat(64),+ },+ timestamp: "2026-08-31T21:00:00.000Z",+} as const;++const rejects = (input: unknown) => expect(() => decodeUsage3hEvent(input)).toThrow();++describe("Usage3hEvent", () => {+ it("accepts the fixed anonymous aggregate payload", () => {+ expect(decodeUsage3hEvent(event)).toEqual(event);+ expect(USAGE_3H_COUNTER_KEYS).toHaveLength(96);+ });++ it("defaults queued events from before install tracking to zero", () => {+ const legacyProperties = Object.fromEntries(+ Object.entries(event.properties).filter(([key]) => key !== "new_installations"),+ );++ expect(+ decodeUsage3hEvent({ ...event, properties: legacyProperties }).properties.new_installations,+ ).toBe(0);+ });++ it("rejects unknown events and properties", () => {+ rejects({ ...event, event: "turn_completed" });+ rejects({ ...event, prompt: "private" });+ rejects({ ...event, properties: { ...event.properties, thread_id: "thread-1" } });+ });++ it("rejects free text, invalid enums, and invalid versions", () => {+ rejects({ ...event, distinct_id: "installation-name" });+ rejects({ ...event, properties: { ...event.properties, provider: "custom-provider" } });+ rejects({ ...event, properties: { ...event.properties, app_version: "v1 latest" } });+ rejects({+ ...event,+ properties: { ...event.properties, app_version: `1.2.3+${"a".repeat(59)}` },+ });+ });++ it("rejects negative, fractional, and oversized counters", () => {+ rejects({ ...event, properties: { ...event.properties, new_installations: 2 } });+ rejects({ ...event, properties: { ...event.properties, failed_turns: -1 } });+ rejects({ ...event, properties: { ...event.properties, bot_replies: 1.5 } });+ rejects({+ ...event,+ properties: { ...event.properties, user_messages: USAGE_3H_COUNTER_MAX + 1 },+ });+ });++ it("rejects invalid buckets, timestamps, and PostHog privacy properties", () => {+ rejects({+ ...event,+ properties: { ...event.properties, bucket_start: "2026-08-31T19:00:00.000Z" },+ });+ rejects({+ ...event,+ properties: { ...event.properties, bucket_start: "2026-02-31T18:00:00.000Z" },+ });+ rejects({ ...event, timestamp: "2026-08-31T20:59:59.999Z" });+ rejects({+ ...event,+ properties: { ...event.properties, $process_person_profile: true },+ });+ rejects({ ...event, properties: { ...event.properties, $geoip_disable: false } });+ rejects({ ...event, properties: { ...event.properties, $ip: "192.0.2.1" } });+ rejects({ ...event, properties: { ...event.properties, $insert_id: "not-a-hash" } });+ });+});diff --git a/packages/contracts/src/analytics.ts b/packages/contracts/src/analytics.tsnew file mode 100644index 000000000..0b7d8814d--- /dev/null+++ b/packages/contracts/src/analytics.ts@@ -0,0 +1,238 @@+import * as DateTime from "effect/DateTime";+import * as Effect from "effect/Effect";+import * as Option from "effect/Option";+import * as Schema from "effect/Schema";++export const USAGE_3H_COUNTER_MAX = 1_000_000;+export const USAGE_BASE_COUNTER_KEYS = [+ "new_installations",+ "bots_created",+ "bots_deleted",+ "bots_total",+ "user_messages",+ "bot_replies",+ "failed_turns",+ "group_messages",+ "external_messages",+ "voice_sessions",+ "browser_tasks",+ "routines_run",+ "routine_failures",+ "connector_calls",+ "connector_failures",+ "approvals_requested",+ "approvals_accepted",+ "approvals_rejected",+] as const;++export const USAGE_PROVIDER_IDS = [+ "codex",+ "claude",+ "cursor",+ "grok",+ "kimi",+ "opencode",+ "other",+] as const;++export const USAGE_SANDBOX_IDS = [+ "none",+ "local",+ "vercel",+ "akeru_cloud",+ "upstash",+ "other",+] as const;++export const USAGE_TOOL_IDS = [+ "command_execution",+ "file_change",+ "mcp_tool_call",+ "dynamic_tool_call",+ "collab_agent_tool_call",+ "web_search",+ "image_view",+] as const;++export const USAGE_BROWSER_PROVIDER_IDS = USAGE_PROVIDER_IDS;++// Public catalog slugs only. Unknown and custom MCP servers never leave the installation.+export const USAGE_PLUGIN_IDS = [+ "ahrefs",+ "apify",+ "apollo",+ "asana",+ "atlassian",+ "attio",+ "canva",+ "cloudflare",+ "coda",+ "context",+ "customer_io",+ "datadog",+ "docusign",+ "dropbox",+ "exa",+ "executor",+ "figma",+ "firecrawl",+ "framer",+ "github",+ "help_scout",+ "hubspot",+ "intercom",+ "lemon_squeezy",+ "linear",+ "mobbin",+ "monday",+ "netlify",+ "notion",+ "paddle",+ "paper",+ "parallel_search",+ "paypal",+ "pipedrive",+ "posthog",+ "railway",+ "render",+ "salesforce",+ "semrush",+ "sentry",+ "sequenzy",+ "shopify",+ "slack",+ "stripe",+ "superside",+ "tavily",+ "typefully",+ "vercel",+ "webflow",+ "zendesk",+ "zernio",+] as const;++export const USAGE_PROVIDER_COUNTER_KEYS = USAGE_PROVIDER_IDS.map(+ (id) => `provider_turns_${id}` as const,+);+export const USAGE_SANDBOX_COUNTER_KEYS = USAGE_SANDBOX_IDS.map(+ (id) => `sandbox_turns_${id}` as const,+);+export const USAGE_TOOL_COUNTER_KEYS = USAGE_TOOL_IDS.map((id) => `tool_calls_${id}` as const);+export const USAGE_BROWSER_PROVIDER_COUNTER_KEYS = USAGE_BROWSER_PROVIDER_IDS.map(+ (id) => `browser_searches_${id}` as const,+);+export const USAGE_PLUGIN_COUNTER_KEYS = USAGE_PLUGIN_IDS.map(+ (id) => `plugin_enabled_${id}` as const,+);+export const USAGE_3H_COUNTER_KEYS = [+ ...USAGE_BASE_COUNTER_KEYS,+ ...USAGE_PROVIDER_COUNTER_KEYS,+ ...USAGE_SANDBOX_COUNTER_KEYS,+ ...USAGE_TOOL_COUNTER_KEYS,+ ...USAGE_BROWSER_PROVIDER_COUNTER_KEYS,+ ...USAGE_PLUGIN_COUNTER_KEYS,+] as const;+export type UsageCounterKey = (typeof USAGE_3H_COUNTER_KEYS)[number];++const UsageCounter = Schema.Int.check(+ Schema.isBetween({ minimum: 0, maximum: USAGE_3H_COUNTER_MAX }),+);+const AppVersion = Schema.String.check(+ Schema.isMaxLength(64),+ Schema.isPattern(+ /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/,+ ),+);+const ThreeHourUtcBucket = Schema.String.check(+ Schema.isPattern(/^\d{4}-\d{2}-\d{2}T(?:00|03|06|09|12|15|18|21):00:00\.000Z$/),+);+const InsertId = Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/));++export const UsageOperatingSystem = Schema.Literals(["darwin", "linux", "win32", "other"]);+export type UsageOperatingSystem = typeof UsageOperatingSystem.Type;++export const UsageArchitecture = Schema.Literals(["x64", "arm64", "arm", "ia32", "other"]);+export type UsageArchitecture = typeof UsageArchitecture.Type;++export const UsageClientType = Schema.Literals(["none", "web", "desktop", "mobile", "mixed"]);+export type UsageClientType = typeof UsageClientType.Type;++export const UsageAnalyticsProvider = Schema.Literals([+ "none",+ "codex",+ "claude",+ "cursor",+ "grok",+ "kimi",+ "opencode",+ "mixed",+ "other",+]);+export type UsageAnalyticsProvider = typeof UsageAnalyticsProvider.Type;++export const UsageSandboxProvider = Schema.Literals([+ "none",+ "local",+ "vercel",+ "akeru-cloud",+ "upstash",+ "mixed",+ "other",+]);+export type UsageSandboxProvider = typeof UsageSandboxProvider.Type;++const UsageCounters = Schema.Struct({+ ...Object.fromEntries(USAGE_3H_COUNTER_KEYS.map((key) => [key, UsageCounter])),+ new_installations: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 1 })).pipe(+ Schema.withDecodingDefault(Effect.succeed(0)),+ ),+});++export const Usage3hProperties = Schema.Struct({+ app_version: AppVersion,+ operating_system: UsageOperatingSystem,+ architecture: UsageArchitecture,+ client_type: UsageClientType,+ provider: UsageAnalyticsProvider,+ sandbox_provider: UsageSandboxProvider,+ bucket_start: ThreeHourUtcBucket,+ ...UsageCounters.fields,+ $process_person_profile: Schema.Literal(false),+ $geoip_disable: Schema.Literal(true),+ $ip: Schema.Literal("0.0.0.0"),+ $insert_id: InsertId,+});+export type Usage3hProperties = typeof Usage3hProperties.Type &+ Readonly<Record<UsageCounterKey, number>>;++export const Usage3hEvent = Schema.Struct({+ event: Schema.Literal("usage_3h"),+ distinct_id: Schema.String.check(Schema.isUUID()),+ properties: Usage3hProperties,+ timestamp: Schema.String,+}).check(+ Schema.makeFilter(+ ({ properties, timestamp }) => {+ const bucketStart = DateTime.make(properties.bucket_start);+ return (+ Option.isSome(bucketStart) &&+ DateTime.formatIso(bucketStart.value) === properties.bucket_start &&+ DateTime.formatIso(DateTime.add(bucketStart.value, { hours: 3 })) === timestamp+ );+ },+ {+ expected: "timestamp at the close of bucket_start",+ },+ ),+);+export type Usage3hEvent = Omit<typeof Usage3hEvent.Type, "properties"> & {+ readonly properties: Usage3hProperties;+};++const decodeUsage3hEventUnknown = Schema.decodeUnknownSync(Usage3hEvent, {+ onExcessProperty: "error",+});++export function decodeUsage3hEvent(input: unknown): Usage3hEvent {+ return decodeUsage3hEventUnknown(input) as Usage3hEvent;+}diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.tsindex 76e01c188..c6645937e 100644--- a/packages/contracts/src/index.ts+++ b/packages/contracts/src/index.ts@@ -4,6 +4,7 @@ export * from "./akeruTools.ts";export * from "./productFeedback.ts";export * from "./akeruMemory.ts";export * from "./akeruUsage.ts";+export * from "./analytics.ts";export * from "./auth.ts";export * from "./environment.ts";export * from "./environmentHttp.ts";diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.tsindex 2749dced3..cfee9be2e 100644--- a/packages/contracts/src/settings.test.ts+++ b/packages/contracts/src/settings.test.ts@@ -67,6 +67,19 @@ describe("ServerSettings product feedback", () => {});});+describe("ServerSettings analytics", () => {+ it("defaults analytics on and accepts an opt-out patch", () => {+ expect(decodeServerSettings({}).analyticsEnabled).toBe(true);+ expect(decodeServerSettingsPatch({ analyticsEnabled: false })).toEqual({+ analyticsEnabled: false,+ });+ });++ it("rejects a non-boolean analytics patch", () => {+ expect(() => decodeServerSettingsPatch({ analyticsEnabled: "false" })).toThrow();+ });+});+describe("ClaudeSettings auto-compaction", () => {it("uses Claude's default threshold when no override is configured", () => {expect(decodeClaudeSettings({}).autoCompactWindow).toBe("");diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.tsindex 4bd95cb58..2188b516e 100644--- a/packages/contracts/src/settings.ts+++ b/packages/contracts/src/settings.ts@@ -666,6 +666,7 @@ export const ServerSettings = Schema.Struct({Schema.withDecodingDefault(Effect.succeed(false)),),enableProviderUpdateChecks: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),+ analyticsEnabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),productFeedbackEnabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),productFeedbackEndpoint: ProductFeedbackEndpoint.pipe(Schema.withDecodingDefault(Effect.succeed(DEFAULT_PRODUCT_FEEDBACK_ENDPOINT)),@@ -908,6 +909,7 @@ export const ServerSettingsPatch = Schema.Struct({// Server settingsenableLegacyTokenStreaming: Schema.optionalKey(Schema.Boolean),enableProviderUpdateChecks: Schema.optionalKey(Schema.Boolean),+ analyticsEnabled: Schema.optionalKey(Schema.Boolean),productFeedbackEnabled: Schema.optionalKey(Schema.Boolean),productFeedbackEndpoint: Schema.optionalKey(ProductFeedbackEndpoint),botSandboxBrowserSharing: Schema.optionalKey(BotSandboxBrowserSharing),