Skip to content

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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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<Ana
Layer.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.ts
index 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: Server
fs.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.ts
index 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 instance
Layer.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 se
Layer.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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/ProjectionSna
import * 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.ts
index 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.ts
index 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.ts
deleted file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
index 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.tsx
index 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 })}
+ />
+ }
+ />
<SettingsRow
title="Product feedback"
control={
diff --git a/apps/web/src/components/settings/settingsSearch.test.ts b/apps/web/src/components/settings/settingsSearch.test.ts
index 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.ts
index 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.md
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 settings
enableLegacyTokenStreaming: 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),