Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: add host-pluggable analytics contract (#891)

harshil-20968d3913895dac
diff --git a/.changeset/trueforge-ui-analytics.md b/.changeset/trueforge-ui-analytics.md
new file mode 100644
index 000000000..357b3a2f7
--- /dev/null
+++ b/.changeset/trueforge-ui-analytics.md
@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge-ui": patch
+"@truefoundry/trueforge": patch
+---
+
+Add a host-pluggable analytics contract (`analytics.track` / `AnalyticsProvider`) with a shared event catalog and first-wave click instrumentation. Hosts own the vendor sink; the SDK never ships PostHog.
diff --git a/.cursor/rules/trueforge-ui-analytics.mdc b/.cursor/rules/trueforge-ui-analytics.mdc
new file mode 100644
index 000000000..b98d30c1c
--- /dev/null
+++ b/.cursor/rules/trueforge-ui-analytics.mdc
@@ -0,0 +1,13 @@
+---
+description: trueforge-ui product analytics — host sink, event catalog, container fire sites
+globs: packages/trueforge-ui/src/**/*.{ts,tsx}
+alwaysApply: false
+---
+
+# trueforge-ui analytics
+
+- Host plugs `analytics.track` on `<TrueForgeUI />` (or mounts `AnalyticsProvider`). Do **not** add PostHog or other vendor SDKs in this package.
+- Event names live in `src/analytics/events.ts` (`AnalyticsEvents`). New clicks add a catalog entry + fire site in the same PR.
+- Prefer wrapping **container** callbacks over atom internals so visual slot overrides keep tracking.
+- `useTrackAnalytics()` must no-op when unset; never throw for missing host.
+- Intent comments only on the provider and non-obvious fire sites (not restating the call).
diff --git a/packages/frontend/package.json b/packages/frontend/package.json
index 106345756..7a3d6b8b2 100644
--- a/packages/frontend/package.json
+++ b/packages/frontend/package.json
@@ -30,6 +30,7 @@
"@truefoundry/trueforge-sdk": "workspace:*",
"@truefoundry/trueforge-ui": "workspace:*",
"monaco-editor": "^0.57.0",
+ "posthog-js": "^1.434.17",
"react": "^19.2.4",
"react-dom": "^19.2.4",
"react-router-dom": "^7.18.2",
diff --git a/packages/frontend/src/App.tsx b/packages/frontend/src/App.tsx
index 7099040f8..ec1f22679 100644
--- a/packages/frontend/src/App.tsx
+++ b/packages/frontend/src/App.tsx
@@ -3,6 +3,7 @@ import {
ThemeProvider,
TrueForgeUI,
useTheme,
+ type AnalyticsConfig,
type SlotOverrides,
type ThemeConfig,
} from '@truefoundry/trueforge-ui';
@@ -12,6 +13,7 @@ import {
listModels,
type HarnessAgentSpec,
} from '@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter';
+import posthog from 'posthog-js';
import { useEffect, useMemo, useState } from 'react';
import { ThinkingOrb } from 'thinking-orbs';
import { AuthErrorScreen } from './AuthErrorScreen';
@@ -23,6 +25,31 @@ import { LogoutButton } from './LogoutButton';
import { NewAgentWelcomeScreen } from './NewAgentWelcomeScreen';
import { API_BASE_URL, uiRouterBasename } from './publicPath';
+const POSTHOG_API_KEY = import.meta.env.VITE_POSTHOG_API_KEY;
+const POSTHOG_HOST = import.meta.env.VITE_POSTHOG_HOST ?? 'https://us.i.posthog.com';
+
+function initAnalytics(): void {
+ if (!POSTHOG_API_KEY) {
+ return;
+ }
+ posthog.init(POSTHOG_API_KEY, {
+ api_host: POSTHOG_HOST,
+ autocapture: false,
+ capture_pageview: false,
+ disable_session_recording: true,
+ });
+}
+
+initAnalytics();
+
+const hostAnalytics: AnalyticsConfig | undefined = POSTHOG_API_KEY
+ ? {
+ track: (eventName, data) => {
+ posthog.capture(eventName, data);
+ },
+ }
+ : undefined;
+
/** Shared cookie/OIDC fetch for boot helpers and `<TrueForgeUI server />`. */
const authAwareFetch = createAuthAwareFetch();
// UI + API share the public prefix from `window.__TRUEFORGE_BASE_PATH__`.
@@ -221,6 +248,7 @@ export function App() {
overrides={overrides}
theme={appTheme}
className="app-assistant"
+ {...(hostAnalytics ? { analytics: hostAnalytics } : {})}
/>
</div>
);
diff --git a/packages/frontend/src/vite-env.d.ts b/packages/frontend/src/vite-env.d.ts
index 11f02fe2a..8b39cc714 100644
--- a/packages/frontend/src/vite-env.d.ts
+++ b/packages/frontend/src/vite-env.d.ts
@@ -1 +1,10 @@
/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+ readonly VITE_POSTHOG_API_KEY?: string;
+ readonly VITE_POSTHOG_HOST?: string;
+}
+
+interface ImportMeta {
+ readonly env: ImportMetaEnv;
+}
diff --git a/packages/trueforge-ui/AGENTS.md b/packages/trueforge-ui/AGENTS.md
new file mode 100644
index 000000000..bb056d1b2
--- /dev/null
+++ b/packages/trueforge-ui/AGENTS.md
@@ -0,0 +1,14 @@
+# @truefoundry/trueforge-ui
+
+- Atoms are presentational; containers wire runtime hooks and resolve atoms via `useSlot`.
+- New JSX-bearing atoms MUST augment `AtomSlots`, register in `defaultSlots`, and be consumed via `useSlot` (see `.cursor/rules/trueforge-ui-slots.mdc`).
+- AgentUIServer / server-port types MUST be re-exported from `src/server/types.ts` only — no parallel hand-written DTOs.
+- UI lengths use `rem` (1rem = 16px); prefer Tailwind scale utilities.
+
+## Analytics
+
+- The analytics sink is host-only. This package MUST NOT depend on PostHog or any other vendor SDK.
+- Canonical event names live only in `src/analytics/events.ts` (`AnalyticsEvents`).
+- Fire from containers wrapping atom callbacks (or documented atom chrome: settings, config trigger, share). Do not duplicate sinks.
+- `useTrackAnalytics()` MUST no-op when no host `track` is provided (never throw).
+- New clickable product actions MUST add a catalog entry and a fire site in the same change.
diff --git a/packages/trueforge-ui/CLAUDE.md b/packages/trueforge-ui/CLAUDE.md
new file mode 100644
index 000000000..43c994c2d
--- /dev/null
+++ b/packages/trueforge-ui/CLAUDE.md
@@ -0,0 +1 @@
diff --git a/packages/trueforge-ui/README.md b/packages/trueforge-ui/README.md
index 0d5696ac1..15a7e5869 100644
--- a/packages/trueforge-ui/README.md
+++ b/packages/trueforge-ui/README.md
@@ -177,16 +177,31 @@ const server = createTrueForgeServer({
/>
```
-| Prop | Type | Required | Description |
-| ------------------ | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
-| `server` | `TrueForgeServerConfig` | ✅ | Built-in `trueforge` config **or** a ready `AgentUIServer`. |
-| `layout` | `LayoutProp` | ✅ | Built-in layout string **or** a custom React component. |
-| `agentConfig` | `AgentConfig` | — | Shell mode: SingleAgent / AgentLibrary / AgentComposer / AgentLibraryWithComposer. Defaults to library + composer. |
-| `theme` | `ThemeConfig` | — | Preset, mode, tokens, brand, icons, **content `classNames`** (see [Theming](#theming)). |
-| `overrides` | `SlotOverrides` | — | Map of slot overrides (see [Overriding components](#overriding-components)). |
-| `className` | `string` | — | Applied to the layout root. |
-| `initialSessionId` | `string` | — | Resume a specific session. |
-| `onError` | `(error: unknown) => void` | — | Host error hook (runtime + server init). |
+| Prop | Type | Required | Description |
+| ------------------ | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| `server` | `TrueForgeServerConfig` | ✅ | Built-in `trueforge` config **or** a ready `AgentUIServer`. |
+| `layout` | `LayoutProp` | ✅ | Built-in layout string **or** a custom React component. |
+| `agentConfig` | `AgentConfig` | — | Shell mode: SingleAgent / AgentLibrary / AgentComposer / AgentLibraryWithComposer. Defaults to library + composer. |
+| `theme` | `ThemeConfig` | — | Preset, mode, tokens, brand, icons, **content `classNames`** (see [Theming](#theming)). |
+| `overrides` | `SlotOverrides` | — | Map of slot overrides (see [Overriding components](#overriding-components)). |
+| `className` | `string` | — | Applied to the layout root. |
+| `initialSessionId` | `string` | — | Resume a specific session. |
+| `onError` | `(error: unknown) => void` | — | Host error hook (runtime + server init). |
+| `analytics` | `{ track: TrackAnalytics }` | — | Host product-analytics sink; SDK never ships a vendor. |
+
+```tsx
+<TrueForgeUI
+ server={server}
+ layout="sidebar"
+ onError={handleError}
+ analytics={{
+ track: (eventName, data) => {
+ // Forward to PostHog / Segment / your sink
+ myAnalytics.capture(eventName, data);
+ },
+ }}
+/>
+```
Later sections use `server` as a `TrueForgeServerConfig` (usually `type: "trueforge"`). For a host-built port, pass the `AgentUIServer` directly.
@@ -577,6 +592,7 @@ See [docs/server.md](./docs/server.md) for the full method list and BYO guidance
| `resolveBrandChrome`, `useBrandName`, `useBrand` | Helpers | Brand chrome look + name for custom layouts |
| Composer / message / tool atoms | Components | Overridable, themeable building blocks |
| `SlotsProvider`, `useSlot`, `useTheme` | API | Overrides + theme mode |
+| `AnalyticsProvider`, `useTrackAnalytics`, `AnalyticsEvents` | API | Host product-analytics sink + event catalog |
| `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer` | Types | Resolved server contract |
| `ThemeConfig`, `LayoutProp`, `SlotOverrides`, `AgentSpec`, … | Types | Configuration contracts |
| `@truefoundry/trueforge-ui/styles.css` | CSS | Optional; auto-injected by `ThemeProvider` |
diff --git a/packages/trueforge-ui/docs/api.md b/packages/trueforge-ui/docs/api.md
index 4ce32cd5b..925960fb0 100644
--- a/packages/trueforge-ui/docs/api.md
+++ b/packages/trueforge-ui/docs/api.md
@@ -65,6 +65,8 @@ Custom servers remain permissive unless they provide the optional port.
| `Thread` | Full thread + composer |
| `ThreadContainer`, `ComposerContainer`, `ThreadListContainer` | Building blocks |
| `ToasterProvider`, `useToaster`, `useToasterOptional` | Success and error toasts |
+| `AnalyticsProvider`, `useTrackAnalytics` | Host product-analytics sink |
+| `AnalyticsEvents`, `AnalyticsConfig`, `TrackAnalytics` | Event catalog + types |
| Other `*Container` exports | Advanced message / tool wiring |
## Slots / theme
diff --git a/packages/trueforge-ui/docs/architecture.md b/packages/trueforge-ui/docs/architecture.md
index 0b75d84de..345412d06 100644
--- a/packages/trueforge-ui/docs/architecture.md
+++ b/packages/trueforge-ui/docs/architecture.md
@@ -53,3 +53,18 @@ Default atoms use CSS variables from the auto-injected stylesheet (scoped to
`ToasterProvider` shows success and error toasts. Descriptions from gateway
errors are truncated for display.
+
+## Analytics
+
+`AnalyticsProvider` forwards product events to a host-supplied `track` sink.
+The SDK never ships a vendor client (e.g. PostHog). Mount order inside
+`TrueForgeUI`: under `SlotsProvider` / `ServerProvider`, wrapping
+`ToasterProvider` so chrome and chat share one sink.
+
+- Pass `analytics={{ track }}` on `<TrueForgeUI />`, or mount
+ `AnalyticsProvider` yourself around a custom compose tree.
+- `useTrackAnalytics()` always returns a function (no-op when unset).
+- Event names live in `AnalyticsEvents` (`src/analytics/events.ts`).
+- Prefer firing from **containers** that wrap atom callbacks so visual slot
+ overrides keep tracking. Atom-owned chrome (settings, config trigger, share)
+ may call the hook directly.
diff --git a/packages/trueforge-ui/docs/customization.md b/packages/trueforge-ui/docs/customization.md
index d0d16a1f7..12e48c671 100644
--- a/packages/trueforge-ui/docs/customization.md
+++ b/packages/trueforge-ui/docs/customization.md
@@ -173,6 +173,14 @@ Notes on behaviour:
Hosts serving the SDK must send the app shell for unknown paths (SPA
fallback), otherwise deep links 404 before React boots.
+## Analytics and slot overrides
+
+Product analytics fire from **containers** that wrap atom callbacks (`onCopy`,
+`onSubmit`, …). Visual slot overrides that keep those props continue to track
+automatically. Overrides that invent new click paths should call
+`useTrackAnalytics()` (and use `AnalyticsEvents`) themselves. Pass
+`analytics={{ track }}` on `<TrueForgeUI />` — the SDK does not ship a vendor.
+
## Custom layout
Pass a React component as `layout` to own chrome; compose exported
diff --git a/packages/trueforge-ui/src/analytics/AnalyticsProvider.tsx b/packages/trueforge-ui/src/analytics/AnalyticsProvider.tsx
new file mode 100644
index 000000000..306d086b6
--- /dev/null
+++ b/packages/trueforge-ui/src/analytics/AnalyticsProvider.tsx
@@ -0,0 +1,36 @@
+'use client';
+
+import { createContext, useCallback, useContext, useMemo, type ReactNode } from 'react';
+
+import type { AnalyticsEventProps, TrackAnalytics } from './types.js';
+
+// Host owns vendor identify/group/gating; SDK only forwards (name, props) and no-ops when unset
+// so tests and embeds work without a host analytics sink.
+const AnalyticsContext = createContext<TrackAnalytics | null>(null);
+
+const noopTrack: TrackAnalytics = () => {};
+
+export function AnalyticsProvider({ track, children }: { track?: TrackAnalytics; children: ReactNode }) {
+ const stableTrack = useCallback<TrackAnalytics>(
+ (eventName, data) => {
+ // Fire sites call this right before the product action; a broken sink must not block it.
+ try {
+ track?.(eventName, data);
+ } catch (error) {
+ console.error('[trueforge-ui] analytics track failed', error);
+ }
+ },
+ [track],
+ );
+
+ const value = useMemo(() => (track == null ? null : stableTrack), [stableTrack, track]);
+
+ return <AnalyticsContext.Provider value={value}>{children}</AnalyticsContext.Provider>;
+}
+
+/** Always-safe tracker: host `track` when mounted, otherwise a no-op. */
+export function useTrackAnalytics(): TrackAnalytics {
+ return useContext(AnalyticsContext) ?? noopTrack;
+}
+
+export type { AnalyticsEventProps, TrackAnalytics };
diff --git a/packages/trueforge-ui/src/analytics/events.ts b/packages/trueforge-ui/src/analytics/events.ts
new file mode 100644
index 000000000..f3ad0e696
--- /dev/null
+++ b/packages/trueforge-ui/src/analytics/events.ts
@@ -0,0 +1,76 @@
+/**
+ * Public event-name contract for hosts (e.g. PostHog). Keep names stable — renaming is a breaking change.
+ */
+export const AnalyticsEvents = {
+ Message: {
+ SENT: 'agent.message_sent',
+ CANCELLED: 'agent.message_cancelled',
+ COPIED: 'agent.message_copied',
+ EDIT_STARTED: 'agent.message_edit_started',
+ RETRIED: 'agent.message_retried',
+ },
+ Attachment: {
+ PICKED: 'agent.attachment_picked',
+ },
+ Session: {
+ NEW: 'agent.session_new',
+ SELECTED: 'agent.session_selected',
+ DELETED: 'agent.session_deleted',
+ RENAMED: 'agent.session_renamed',
+ SHARE_OPENED: 'agent.session_share_opened',
+ SHARE_LINK_COPIED: 'agent.session_share_link_copied',
+ },
+ Tool: {
+ APPROVAL_RESOLVED: 'agent.tool_approval_resolved',
+ },
+ AskUser: {
+ SUBMITTED: 'agent.ask_user_submitted',
+ },
+ Config: {
+ OPENED: 'agent.config_opened',
+ },
+ Settings: {
+ OPENED: 'agent.settings_opened',
+ CLOSED: 'settings.closed',
+ SECTION_CHANGED: 'settings.section_changed',
+ MODEL_PROVIDER_SAVED: 'settings.model_provider_saved',
+ MODEL_PROVIDER_DELETED: 'settings.model_provider_deleted',
+ CONNECTOR_SAVED: 'settings.connector_saved',
+ CONNECTOR_DISCONNECTED: 'settings.connector_disconnected',
+ CONNECTOR_DELETED: 'settings.connector_deleted',
+ SKILL_IMPORTED: 'settings.skill_imported',
+ SKILL_DELETED: 'settings.skill_deleted',
+ SANDBOX_PROVIDER_SAVED: 'settings.sandbox_provider_saved',
+ SANDBOX_PROVIDER_DELETED: 'settings.sandbox_provider_deleted',
+ WEB_SEARCH_PROVIDER_SAVED: 'settings.web_search_provider_saved',
+ },
+ Library: {
+ OPENED: 'library.opened',
+ CLOSED: 'library.closed',
+ AGENT_TRIED: 'library.agent_tried',
+ AGENT_EDITED: 'library.agent_edited',
+ AGENT_DETAILS_OPENED: 'library.agent_details_opened',
+ AGENT_SCHEDULES_OPENED: 'library.agent_schedules_opened',
+ },
+ AgentDetails: {
+ OPENED: 'agent_details.opened',
+ TAB_CHANGED: 'agent_details.tab_changed',
+ },
+ SessionsBrowser: {
+ OPENED: 'sessions_browser.opened',
+ },
+ Schedule: {
+ PAGE_OPENED: 'schedule.page_opened',
+ CREATED: 'schedule.created',
+ EDITED: 'schedule.edited',
+ DELETED: 'schedule.deleted',
+ TOGGLED: 'schedule.toggled',
+ RUN_NOW: 'schedule.run_now',
+ },
+ Environment: {
+ PAGE_OPENED: 'environment.page_opened',
+ CREATED: 'environment.created',
+ EDITED: 'environment.edited',
+ DELETED: 'environment.deleted',
+ },
+} as const;
diff --git a/packages/trueforge-ui/src/analytics/index.ts b/packages/trueforge-ui/src/analytics/index.ts
new file mode 100644
index 000000000..ca1649542
--- /dev/null
+++ b/packages/trueforge-ui/src/analytics/index.ts
@@ -0,0 +1,4 @@
+export { AnalyticsProvider, useTrackAnalytics } from './AnalyticsProvider.js';
+export { AnalyticsEvents } from './events.js';
+export { withSessionProps } from './sessionProps.js';
+export type { AnalyticsConfig, AnalyticsEventProps, TrackAnalytics } from './types.js';
diff --git a/packages/trueforge-ui/src/analytics/sessionProps.ts b/packages/trueforge-ui/src/analytics/sessionProps.ts
new file mode 100644
index 000000000..e13ae678f
--- /dev/null
+++ b/packages/trueforge-ui/src/analytics/sessionProps.ts
@@ -0,0 +1,18 @@
+import type { AnalyticsEventProps } from './types.js';
+
+/**
+ * Attach session and agent identity to an event when the shell actually has it.
+ * Null, undefined, and empty strings are omitted so a new chat (no session yet)
+ * or an unnamed draft does not send blank `session_id` / `agent_id` to the host.
+ */
+export function withSessionProps(
+ base: AnalyticsEventProps | undefined,
+ session: { sessionId?: string | null; agentId?: string | null; agentName?: string | null },
+): AnalyticsEventProps {
+ return {
+ ...base,
+ ...(session.sessionId != null && session.sessionId !== '' ? { session_id: session.sessionId } : {}),
+ ...(session.agentId != null && session.agentId !== '' ? { agent_id: session.agentId } : {}),
+ ...(session.agentName != null && session.agentName !== '' ? { agent_name: session.agentName } : {}),
+ };
+}
diff --git a/packages/trueforge-ui/src/analytics/types.ts b/packages/trueforge-ui/src/analytics/types.ts
new file mode 100644
index 000000000..f9d981f66
--- /dev/null
+++ b/packages/trueforge-ui/src/analytics/types.ts
@@ -0,0 +1,10 @@
+/** Props attached to a product-analytics event. Hosts forward these to their vendor. */
+export type AnalyticsEventProps = Record<string, string | number | boolean | undefined>;
+
+/** Host-supplied sink. The SDK never ships a vendor client. */
+export type TrackAnalytics = (eventName: string, data?: AnalyticsEventProps) => void;
+
+/** Optional host analytics config passed to `<TrueForgeUI />`. */
+export type AnalyticsConfig = {
+ track: TrackAnalytics;
+};
diff --git a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
index 357c6d3d6..4689b67e5 100644
--- a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
+++ b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
@@ -2,6 +2,9 @@
import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
+
import { useResourcePermissions } from '../hooks/useResourcePermissions.js';
import { useSessionShareSearch } from '../hooks/useSessionShareSearch.js';
import { Icon } from '../icons/Icon.js';
@@ -521,6 +524,7 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
const sessionsServer = useOptionalAgentSessionsServer();
const scheduleServer = useOptionalScheduleServer();
const SlottedAgentLibraryRow = useSlot('AgentLibraryRow');
+ const track = useTrackAnalytics();
const [query, setQuery] = useState(() => readLibraryShareSearch(window.location.search).agentName ?? '');
const [scheduleByAgent, setScheduleByAgent] = useState<Map<string, AgentScheduleSummary> | null>(null);
const skipNextLibraryShareSyncRef = useRef(false);
@@ -554,9 +558,10 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
}, [open, query]);
const closeLibrary = useCallback(() => {
+ track(AnalyticsEvents.Library.CLOSED);
shell.setLibraryOpen(false);
setQuery('');
- }, [shell]);
+ }, [shell, track]);
useEffect(() => {
if (!open) return;
@@ -608,6 +613,7 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
}, [agents, open, scheduleServer, agentsListEpoch]);
const openSchedulesForAgent = ({ agentId, isNew }: { agentId: string; isNew?: boolean }) => {
+ track(AnalyticsEvents.Library.AGENT_SCHEDULES_OPENED, { agent_id: agentId });
replaceScheduleShareSearch({
agent: null,
status: null,
@@ -625,7 +631,7 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
};
const handleTry = (agent: AgentLibraryEntry) => {
- closeLibrary();
+ track(AnalyticsEvents.Library.AGENT_TRIED, { agent_id: libraryAgentId(agent), agent_name: agent.name });
onSelectAgent?.(agent.name);
shell.selectLibraryAgent({
isMutable: false,
@@ -635,7 +641,7 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
};
const handleEdit = (agent: AgentLibraryEntry, agentSpec: AgentSpec) => {
- closeLibrary();
+ track(AnalyticsEvents.Library.AGENT_EDITED, { agent_id: libraryAgentId(agent), agent_name: agent.name });
onSelectAgent?.(agent.name);
shell.selectLibraryAgent({
isMutable: true,
@@ -680,6 +686,10 @@ export function AgentsLibrary({ onSelectAgent, headerStart }: AgentsLibraryProps
{...(canOpenAgentDetails && agentId != null
? {
onOpen: () => {
+ track(AnalyticsEvents.Library.AGENT_DETAILS_OPENED, {
+ agent_id: agentId,
+ agent_name: agent.name,
+ });
updateShareSearch({
agentId,
tab: 'overview',
diff --git a/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx b/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx
index 9a2248aaa..1a5b8d9f8 100644
--- a/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx
+++ b/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx
@@ -2,6 +2,8 @@
import { useEffect, useState } from 'react';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { Icon } from '../icons/Icon.js';
import { useOptionalServer } from '../server/ServerContext.js';
import { useOptionalShellMode } from '../server/ShellModeContext.js';
@@ -17,6 +19,7 @@ export type AgentsLibraryButtonProps = {
export function AgentsLibraryButton({ className, compact = false }: AgentsLibraryButtonProps) {
const server = useOptionalServer();
const shell = useOptionalShellMode();
+ const track = useTrackAnalytics();
const [countLabel, setCountLabel] = useState<string | null>(null);
const enabled = shell?.isLibraryEnabled === true && server != null;
@@ -63,7 +66,10 @@ export function AgentsLibraryButton({ className, compact = false }: AgentsLibrar
'bg-primary-button-bg font-medium text-primary-button-text hover:bg-primary-button-hover hover:text-primary-button-text',
),
})}
- onClick={() => shell?.setLibraryOpen(true)}
+ onClick={() => {
+ if (!libraryOpen) track(AnalyticsEvents.Library.OPENED);
+ shell?.setLibraryOpen(true);
+ }}
>
<Icon name="library-big" size={compact ? 14 : undefined} />
{compact ? (
diff --git a/packages/trueforge-ui/src/atoms/EnvironmentsButton.tsx b/packages/trueforge-ui/src/atoms/EnvironmentsButton.tsx
index e1e1d012c..8fd258f57 100644
--- a/packages/trueforge-ui/src/atoms/EnvironmentsButton.tsx
+++ b/packages/trueforge-ui/src/atoms/EnvironmentsButton.tsx
@@ -1,5 +1,7 @@
'use client';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { Icon } from '../icons/Icon.js';
import { useOptionalSandboxEnvironmentServer } from '../server/ServerContext.js';
import { useOptionalShellMode } from '../server/ShellModeContext.js';
@@ -15,6 +17,7 @@ export type EnvironmentsButtonProps = {
export function EnvironmentsButton({ className, compact = false }: EnvironmentsButtonProps) {
const shell = useOptionalShellMode();
const sandboxEnvironmentServer = useOptionalSandboxEnvironmentServer();
+ const track = useTrackAnalytics();
const enabled = isEnvironmentsChromeEnabled({ sandboxEnvironments: sandboxEnvironmentServer }) && shell != null;
const open = shell?.environmentsOpen === true;
@@ -38,7 +41,10 @@ export function EnvironmentsButton({ className, compact = false }: EnvironmentsB
'bg-primary-button-bg font-medium text-primary-button-text hover:bg-primary-button-hover hover:text-primary-button-text',
),
})}
- onClick={() => shell.setEnvironmentsOpen(!open)}
+ onClick={() => {
+ if (!open) track(AnalyticsEvents.Environment.PAGE_OPENED);
+ shell.setEnvironmentsOpen(!open);
+ }}
>
<Icon name="monitor" size={compact ? 14 : undefined} />
{compact ? (
diff --git a/packages/trueforge-ui/src/atoms/SchedulesButton.tsx b/packages/trueforge-ui/src/atoms/SchedulesButton.tsx
index 4eb9490cd..dd1945813 100644
--- a/packages/trueforge-ui/src/atoms/SchedulesButton.tsx
+++ b/packages/trueforge-ui/src/atoms/SchedulesButton.tsx
@@ -1,5 +1,7 @@
'use client';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { Icon } from '../icons/Icon.js';
import { useOptionalScheduleServer } from '../server/ServerContext.js';
import { useOptionalShellMode } from '../server/ShellModeContext.js';
@@ -15,6 +17,7 @@ export type SchedulesButtonProps = {
export function SchedulesButton({ className, compact = false }: SchedulesButtonProps) {
const shell = useOptionalShellMode();
const scheduleServer = useOptionalScheduleServer();
+ const track = useTrackAnalytics();
const enabled = isSchedulesChromeEnabled({ schedules: scheduleServer }) && shell != null;
const open = shell?.schedulesOpen === true;
@@ -38,7 +41,10 @@ export function SchedulesButton({ className, compact = false }: SchedulesButtonP
'bg-primary-button-bg font-medium text-primary-button-text hover:bg-primary-button-hover hover:text-primary-button-text',
),
})}
- onClick={() => shell.setSchedulesOpen(!open)}
+ onClick={() => {
+ if (!open) track(AnalyticsEvents.Schedule.PAGE_OPENED);
+ shell.setSchedulesOpen(!open);
+ }}
>
<Icon name="calendar-clock" size={compact ? 14 : undefined} />
{compact ? (
diff --git a/packages/trueforge-ui/src/atoms/SessionsBrowserButton.tsx b/packages/trueforge-ui/src/atoms/SessionsBrowserButton.tsx
index dee213e4d..505127648 100644
--- a/packages/trueforge-ui/src/atoms/SessionsBrowserButton.tsx
+++ b/packages/trueforge-ui/src/atoms/SessionsBrowserButton.tsx
@@ -1,5 +1,7 @@
'use client';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { useSessionShareSearch } from '../hooks/useSessionShareSearch.js';
import { Icon } from '../icons/Icon.js';
import { useOptionalAgentSessionsServer } from '../server/ServerContext.js';
@@ -17,6 +19,7 @@ export type SessionsBrowserButtonProps = {
export function SessionsBrowserButton({ className, compact = false }: SessionsBrowserButtonProps) {
const sessionsServer = useOptionalAgentSessionsServer();
const shell = useOptionalShellMode();
+ const track = useTrackAnalytics();
const { updateShareSearch } = useSessionShareSearch();
const sessionsOpen = shell?.sessionsOpen === true;
const enabled = isSessionsChromeEnabled({ sessions: sessionsServer }) && shell != null;
@@ -42,6 +45,7 @@ export function SessionsBrowserButton({ className, compact = false }: SessionsBr
})}
onClick={() => {
if (!sessionsOpen) {
+ track(AnalyticsEvents.SessionsBrowser.OPENED);
const share = readSessionShareSearch(window.location.search);
updateShareSearch({
view: 'sessions',
diff --git a/packages/trueforge-ui/src/atoms/ShareSessionDialog.tsx b/packages/trueforge-ui/src/atoms/ShareSessionDialog.tsx
index 9c95e3874..155ceb0c9 100644
--- a/packages/trueforge-ui/src/atoms/ShareSessionDialog.tsx
+++ b/packages/trueforge-ui/src/atoms/ShareSessionDialog.tsx
@@ -2,6 +2,8 @@
import type { ReactNode } from 'react';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { useShareSessionDialog, type SessionSharePermission } from '../hooks/useShareSessionDialog.js';
import { Icon } from '../icons/Icon.js';
import { auiInputClass } from './lib/inputClasses.js';
@@ -100,6 +102,7 @@ function AccessSelector({
export function ShareSessionDialog({ sessionId, trigger }: ShareSessionDialogProps) {
const { permission, canManage, loading, shareUrl, copied, tenantId, load, changePermission, copySharedSessionLink } =
useShareSessionDialog(sessionId);
+ const track = useTrackAnalytics();
return (
<DropdownMenu
@@ -107,7 +110,10 @@ export function ShareSessionDialog({ sessionId, trigger }: ShareSessionDialogPro
align="end"
closeOnClick={false}
onOpenChange={open => {
- if (open) void load();
+ if (open) {
+ track(AnalyticsEvents.Session.SHARE_OPENED, { session_id: sessionId });
+ load();
+ }
}}
className="w-120 gap-5 rounded-[0.75rem] p-6 shadow-xs"
>
@@ -139,7 +145,13 @@ export function ShareSessionDialog({ sessionId, trigger }: ShareSessionDialogPro
type="button"
size="large"
className="h-8 shrink-0 rounded px-2.5 text-xs"
- onClick={() => void copySharedSessionLink()}
+ onClick={() => {
+ track(AnalyticsEvents.Session.SHARE_LINK_COPIED, {
+ session_id: sessionId,
+ permission,
+ });
+ copySharedSessionLink();
+ }}
>
<Icon name={copied ? 'check' : 'copy'} size="0.875rem" />
{copied ? 'Copied' : 'Copy'}
diff --git a/packages/trueforge-ui/src/atoms/ShellActions.tsx b/packages/trueforge-ui/src/atoms/ShellActions.tsx
index 99594fffc..02d527a7c 100644
--- a/packages/trueforge-ui/src/atoms/ShellActions.tsx
+++ b/packages/trueforge-ui/src/atoms/ShellActions.tsx
@@ -1,5 +1,7 @@
'use client';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { Icon } from '../icons/Icon.js';
import { useOptionalCatalogServer, useServerCapabilities } from '../server/ServerContext.js';
import { useOptionalShellMode } from '../server/ShellModeContext.js';
@@ -20,6 +22,7 @@ export function ShellActions({
onAction?: () => void;
}) {
const shell = useOptionalShellMode();
+ const track = useTrackAnalytics();
const catalog = useOptionalCatalogServer();
const capabilities = useServerCapabilities();
const { mode, setTheme } = useTheme();
@@ -89,6 +92,7 @@ export function ShellActions({
),
})}
onClick={() => {
+ if (!shell.settingsOpen) track(AnalyticsEvents.Settings.OPENED);
shell.setSettingsOpen(true);
onAction?.();
}}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
index a3ba1f2e9..7767b0a86 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
@@ -1,6 +1,8 @@
'use client';
import { Suspense, useCallback, useEffect, useState } from 'react';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
import { useSessionShareSearch } from '../../hooks/useSessionShareSearch.js';
import {
useOptionalAgentMetricsServer,
@@ -25,6 +27,7 @@ export function AgentDetailsPage({ agentId }: AgentDetailsPageProps) {
const shell = useShellMode();
const isMobile = useIsMobile();
const share = useSessionShareSearch();
+ const track = useTrackAnalytics();
const { updateShareSearch } = share;
const requestedTab = libraryAgentTabFromSearch(share, agentId);
const showMetrics = isMetricsChromeEnabled({ metrics: metricsServer });
@@ -59,6 +62,12 @@ export function AgentDetailsPage({ agentId }: AgentDetailsPageProps) {
shell.closeLibraryAgent();
}, [shell, updateShareSearch]);
+ useEffect(() => {
+ track(AnalyticsEvents.AgentDetails.OPENED, { agent_id: agentId });
+ // Track only on mount (agentId-keyed remount boundary handles agent switches).
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
useEffect(() => {
const onKeyDown = (event: KeyboardEvent) => {
if (event.key !== 'Escape') return;
@@ -169,15 +178,16 @@ export function AgentDetailsPage({ agentId }: AgentDetailsPageProps) {
<AgentMetricsTimeRangeFilter timeRange={metricsTimeRange} onTimeRangeChange={setMetricsTimeRange} />
) : null
}
- onTabChange={tab =>
+ onTabChange={tab => {
+ track(AnalyticsEvents.AgentDetails.TAB_CHANGED, { agent_id: agentId, tab });
updateShareSearch({
agentId,
tab,
view: null,
timeRange: null,
...(tab === 'sessions' ? {} : { sessionId: null }),
- })
- }
+ });
+ }}
/>
) : null}
{/* Tabs own their scrolling so long instructions / code samples stay inside their card. */}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
index f23132172..8fe911106 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
@@ -3,6 +3,9 @@
import { useCallback, useEffect, useMemo, useRef, useState, type ComponentType } from 'react';
import { Group, Panel, Separator } from 'react-resizable-panels';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
+import { withSessionProps } from '../../analytics/sessionProps.js';
import { useToasterOptional } from '../../containers/ToasterContainer.js';
import { useResourcePermissions } from '../../hooks/useResourcePermissions.js';
import { useSessionShareSearch } from '../../hooks/useSessionShareSearch.js';
@@ -57,6 +60,7 @@ export function AgentSessions({
const sessionsServer = useAgentSessionsServer();
const chatServer = useServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const shell = useOptionalShellMode();
const routes = useOptionalResolvedRoutes();
const { sessionId: querySessionId, updateShareSearch } = useSessionShareSearch();
@@ -261,6 +265,10 @@ export function AgentSessions({
setPendingDelete(null);
try {
await chatServer.deleteSession({ sessionId: entry.id });
+ track(
+ AnalyticsEvents.Session.DELETED,
+ withSessionProps(undefined, { sessionId: entry.id, agentName: entry.agentName }),
+ );
setEntries(current => current.filter(item => item.id !== entry.id));
if (selectedSessionId === entry.id) {
updateShareSearch({ sessionId: null });
diff --git a/packages/trueforge-ui/src/atoms/draft/DraftAgentConfigTrigger.tsx b/packages/trueforge-ui/src/atoms/draft/DraftAgentConfigTrigger.tsx
index b5f84ed3f..d65767e7a 100644
--- a/packages/trueforge-ui/src/atoms/draft/DraftAgentConfigTrigger.tsx
+++ b/packages/trueforge-ui/src/atoms/draft/DraftAgentConfigTrigger.tsx
@@ -1,5 +1,8 @@
'use client';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
+import { withSessionProps } from '../../analytics/sessionProps.js';
import { Icon } from '../../icons/Icon.js';
import { useOptionalShellMode } from '../../server/ShellModeContext.js';
import { auiButtonClass } from '../lib/buttonClasses.js';
@@ -12,6 +15,7 @@ export type DraftAgentConfigTriggerProps = {
export function DraftAgentConfigTrigger({ disabled, isRunning }: DraftAgentConfigTriggerProps) {
const shell = useOptionalShellMode();
+ const track = useTrackAnalytics();
const open = shell?.agentConfigOpen === true;
return (
@@ -23,7 +27,20 @@ export function DraftAgentConfigTrigger({ disabled, isRunning }: DraftAgentConfi
aria-expanded={open}
disabled={disabled || isRunning || shell == null}
className={auiButtonClass({ variant: 'ghost', size: 'icon', className: 'size-8' })}
- onClick={() => shell?.setAgentConfigOpen(!open)}
+ onClick={() => {
+ const nextOpen = !open;
+ if (nextOpen) {
+ track(
+ AnalyticsEvents.Config.OPENED,
+ withSessionProps(undefined, {
+ ...(shell?.mode.status === 'active'
+ ? { agentId: shell.mode.agentId, agentName: shell.mode.agentName }
+ : {}),
+ }),
+ );
+ }
+ shell?.setAgentConfigOpen(nextOpen);
+ }}
>
<Icon name="sliders" className="size-3.5" />
</button>
diff --git a/packages/trueforge-ui/src/atoms/draft/DraftComposerSections.tsx b/packages/trueforge-ui/src/atoms/draft/DraftComposerSections.tsx
index 5832d8f35..fa2ade165 100644
--- a/packages/trueforge-ui/src/atoms/draft/DraftComposerSections.tsx
+++ b/packages/trueforge-ui/src/atoms/draft/DraftComposerSections.tsx
@@ -1,5 +1,8 @@
'use client';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
+import { withSessionProps } from '../../analytics/sessionProps.js';
import { Icon } from '../../icons/Icon.js';
import { shellIsCreateAgent, useOptionalShellMode } from '../../server/ShellModeContext.js';
import { useSlot } from '../../theme/SlotsProvider.js';
@@ -12,6 +15,7 @@ import { DraftReasoningEffortSelector } from './DraftReasoningEffortSelector.js'
export function DraftComposerLeftSection({ disabled, isRunning, onAttach }: ComposerLeftSectionProps) {
const shell = useOptionalShellMode();
+ const track = useTrackAnalytics();
const DraftCompositeSelector = useSlot('DraftCompositeSelector');
const DraftAgentConfigTrigger = useSlot('DraftAgentConfigTrigger');
const DraftComposerActionsMenu = useSlot('DraftComposerActionsMenu');
@@ -23,7 +27,17 @@ export function DraftComposerLeftSection({ disabled, isRunning, onAttach }: Comp
id: 'agent-config',
label: 'Agent config',
icon: 'sliders',
- onSelect: () => shell?.setAgentConfigOpen(true),
+ onSelect: () => {
+ track(
+ AnalyticsEvents.Config.OPENED,
+ withSessionProps(undefined, {
+ ...(shell?.mode.status === 'active'
+ ? { agentId: shell.mode.agentId, agentName: shell.mode.agentName }
+ : {}),
+ }),
+ );
+ shell?.setAgentConfigOpen(true);
+ },
},
...(onAttach === undefined
? []
diff --git a/packages/trueforge-ui/src/atoms/environments/EnvironmentFormDrawer.tsx b/packages/trueforge-ui/src/atoms/environments/EnvironmentFormDrawer.tsx
index 5a5a120e0..faefab64b 100644
--- a/packages/trueforge-ui/src/atoms/environments/EnvironmentFormDrawer.tsx
+++ b/packages/trueforge-ui/src/atoms/environments/EnvironmentFormDrawer.tsx
@@ -2,6 +2,8 @@
import { useEffect, useMemo, useState, type FormEvent } from 'react';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
import { useToasterOptional } from '../../containers/ToasterContainer.js';
import { useSandboxEnvironmentServer } from '../../server/ServerContext.js';
import type { SandboxEnvironment, SandboxEnvironmentManifest } from '../../server/types.js';
@@ -34,6 +36,7 @@ type EditorMode = 'form' | 'yaml';
export function EnvironmentFormDrawer({ open, onOpenChange, mode, environment, onSaved }: EnvironmentFormDrawerProps) {
const environmentServer = useSandboxEnvironmentServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [editorMode, setEditorMode] = useState<EditorMode>('form');
const [form, setForm] = useState<EnvironmentFormValues>(() => manifestToFormValues(defaultEnvironmentManifest()));
const [yamlText, setYamlText] = useState(() => manifestToYaml(defaultEnvironmentManifest()));
@@ -122,7 +125,11 @@ export function EnvironmentFormDrawer({ open, onOpenChange, mode, environment, o
setSaving(true);
try {
- await environmentServer.createOrUpdateEnvironment({ manifest });
+ const saved = await environmentServer.createOrUpdateEnvironment({ manifest });
+ track(mode === 'create' ? AnalyticsEvents.Environment.CREATED : AnalyticsEvents.Environment.EDITED, {
+ environment_name: saved.name,
+ environment_id: saved.id,
+ });
toaster?.showSuccess({
title: mode === 'create' ? 'Environment created' : 'Environment updated',
});
diff --git a/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx b/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx
index de5475e02..17a8cef20 100644
--- a/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx
+++ b/packages/trueforge-ui/src/atoms/environments/EnvironmentsPage.tsx
@@ -2,6 +2,8 @@
import { useCallback, useEffect, useMemo, useRef, useState, type ComponentType } from 'react';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
import { useToasterOptional } from '../../containers/ToasterContainer.js';
import { Icon } from '../../icons/Icon.js';
import { useSandboxEnvironmentServer } from '../../server/ServerContext.js';
@@ -56,6 +58,7 @@ export function EnvironmentsPage(_props: EnvironmentsPageProps) {
const environmentServer = useSandboxEnvironmentServer();
const shell = useOptionalShellMode();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [environments, setEnvironments] = useState<SandboxEnvironment[]>([]);
const [loading, setLoading] = useState(true);
@@ -187,6 +190,10 @@ export function EnvironmentsPage(_props: EnvironmentsPageProps) {
setDeleting(true);
try {
await environmentServer.deleteEnvironment({ name: pendingDelete.name });
+ track(AnalyticsEvents.Environment.DELETED, {
+ environment_name: pendingDelete.name,
+ environment_id: pendingDelete.id,
+ });
toaster?.showSuccess({ title: 'Environment deleted' });
setPendingDelete(null);
setPageToken(undefined);
diff --git a/packages/trueforge-ui/src/atoms/schedules/ScheduleFormDrawer.tsx b/packages/trueforge-ui/src/atoms/schedules/ScheduleFormDrawer.tsx
index ca9a1c835..32a14a970 100644
--- a/packages/trueforge-ui/src/atoms/schedules/ScheduleFormDrawer.tsx
+++ b/packages/trueforge-ui/src/atoms/schedules/ScheduleFormDrawer.tsx
@@ -2,6 +2,8 @@
import { useEffect, useMemo, useRef, useState, type FormEvent, type ReactNode } from 'react';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
import { useToasterOptional } from '../../containers/ToasterContainer.js';
import { useResourcePermissions } from '../../hooks/useResourcePermissions.js';
import { Icon } from '../../icons/Icon.js';
@@ -46,6 +48,7 @@ function ScheduleFormDrawerBody({
const server = useServer();
const shell = useOptionalShellMode();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [form, setForm] = useState<ScheduleFormValues>(defaultScheduleFormValues);
const [agentId, setAgentId] = useState(initialAgentId);
const [selectedAgent, setSelectedAgent] = useState<AgentLibraryEntry | null>(null);
@@ -165,6 +168,7 @@ function ScheduleFormDrawerBody({
timezone: form.timezone,
status: schedule.status,
});
+ track(AnalyticsEvents.Schedule.EDITED, { schedule_id: schedule.id, agent_id: schedule.agentId });
onSaved?.();
onOpenChange(false);
return;
@@ -179,6 +183,7 @@ function ScheduleFormDrawerBody({
timezone: form.timezone,
status: 'paused',
});
+ track(AnalyticsEvents.Schedule.EDITED, { schedule_id: saved.id, agent_id: saved.agentId });
onSaved?.();
enterTestView(saved);
toaster?.showSuccess({
@@ -196,6 +201,7 @@ function ScheduleFormDrawerBody({
timezone: form.timezone,
status: 'paused',
});
+ track(AnalyticsEvents.Schedule.CREATED, { schedule_id: saved.id, agent_id: agentId });
onSaved?.();
enterTestView(saved);
toaster?.showSuccess({
diff --git a/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx b/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx
index 18952d345..7c20f6668 100644
--- a/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx
+++ b/packages/trueforge-ui/src/atoms/schedules/SchedulesPage.tsx
@@ -2,6 +2,8 @@
import { useCallback, useEffect, useMemo, useRef, useState, type ComponentType } from 'react';
+import { useTrackAnalytics } from '../../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../../analytics/events.js';
import { useToasterOptional } from '../../containers/ToasterContainer.js';
import { useResourcePermissions } from '../../hooks/useResourcePermissions.js';
import { Icon } from '../../icons/Icon.js';
@@ -156,6 +158,7 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {
const scheduleServer = useScheduleServer();
const server = useServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [schedules, setSchedules] = useState<Schedule[]>([]);
const { allows } = useResourcePermissions({
@@ -332,6 +335,11 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {
const nextStatus: ScheduleStatus = schedule.status === 'active' ? 'paused' : 'active';
try {
await scheduleServer.updateSchedule({ ...schedule, status: nextStatus });
+ track(AnalyticsEvents.Schedule.TOGGLED, {
+ schedule_id: schedule.id,
+ agent_id: schedule.agentId,
+ next_status: nextStatus,
+ });
await loadSchedules({ token: pageToken, size: pageSize, agentId: agentFilter });
} catch (caught) {
toaster?.showError(caught);
@@ -343,6 +351,7 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {
setRunningScheduleIds(prev => new Set(prev).add(schedule.id));
try {
await scheduleServer.createScheduleRun({ scheduleId: schedule.id });
+ track(AnalyticsEvents.Schedule.RUN_NOW, { schedule_id: schedule.id, agent_id: schedule.agentId });
toaster?.showSuccess({ title: 'Run started' });
const runs = await scheduleServer.listScheduleRuns({ scheduleId: schedule.id });
setRunsByScheduleId(prev => ({ ...prev, [schedule.id]: runs }));
@@ -362,6 +371,7 @@ export function SchedulesPage({ agentId }: SchedulesPageProps) {
setPendingDelete(null);
try {
await scheduleServer.deleteSchedule({ id: schedule.id });
+ track(AnalyticsEvents.Schedule.DELETED, { schedule_id: schedule.id, agent_id: schedule.agentId });
resetToFirstPage();
} catch (caught) {
toaster?.showError(caught);
diff --git a/packages/trueforge-ui/src/containers/AskUserContainer.tsx b/packages/trueforge-ui/src/containers/AskUserContainer.tsx
index 9141a121e..b0d20b2d8 100644
--- a/packages/trueforge-ui/src/containers/AskUserContainer.tsx
+++ b/packages/trueforge-ui/src/containers/AskUserContainer.tsx
@@ -9,6 +9,8 @@ import {
type Question,
} from '../atoms/adapters/AskUserPromptAdapter.js';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { useSlot } from '../theme/SlotsProvider.js';
const EMPTY_ANSWER: AskUserAnswerDraft = { radioValue: '', custom: '' };
@@ -16,6 +18,7 @@ const EMPTY_ANSWER: AskUserAnswerDraft = { radioValue: '', custom: '' };
export function AskUserContainer({ disabled = false }: { disabled?: boolean }) {
const AskUserPrompt = useSlot('AskUserPrompt');
const { pending, respond } = useTrueForgeToolResponses();
+ const track = useTrackAnalytics();
const isRunning = useThreadIsRunning();
const item = pending[0];
@@ -73,8 +76,14 @@ export function AskUserContainer({ disabled = false }: { disabled?: boolean }) {
if (disabled || item == null || !allQuestionsAnswered) return;
const content = getResponseForQuestion(item.toolCallId);
if (!content) return;
+ const answer = answers[item.toolCallId] ?? EMPTY_ANSWER;
+ track(AnalyticsEvents.AskUser.SUBMITTED, {
+ tool_call_id: item.toolCallId,
+ question_count: questions.length,
+ is_custom_option: answer.radioValue === ASK_USER_CUSTOM_OPTION,
+ });
respond({ toolCallId: item.toolCallId, content });
- }, [allQuestionsAnswered, disabled, getResponseForQuestion, item, respond]);
+ }, [allQuestionsAnswered, answers, disabled, getResponseForQuestion, item, questions.length, respond, track]);
if (item == null || currentQuestion == null) return null;
diff --git a/packages/trueforge-ui/src/containers/AssistantMessageContainer.tsx b/packages/trueforge-ui/src/containers/AssistantMessageContainer.tsx
index 772b637a7..c17a96251 100644
--- a/packages/trueforge-ui/src/containers/AssistantMessageContainer.tsx
+++ b/packages/trueforge-ui/src/containers/AssistantMessageContainer.tsx
@@ -4,6 +4,10 @@ import { useActionBarCopy, useMessageError, useThreadIsRunning, type PartState }
import { MessagePrimitive, useAuiState, type EnrichedPartState, type GroupByContext } from '@assistant-ui/react';
import { useTrueForgeResumeUnavailable } from '@truefoundry/trueforge-assistant-ui-runtime';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
+import { withSessionProps } from '../analytics/sessionProps.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
import { useSlot } from '../theme/SlotsProvider.js';
import { computeAgentStepsSplit } from '../utils/computeAgentStepsSplit.js';
import { AgentStepsContainer } from './AgentStepsContainer.js';
@@ -40,10 +44,19 @@ export function AssistantMessageContainer() {
const resumeUnavailable = useTrueForgeResumeUnavailable();
const error = useMessageError();
const createdAt = useAuiState(s => s.message.createdAt);
+ const sessionId = useAuiState(s => s.threadListItem.remoteId);
const isMessageRunning = useAuiState(s => s.message.status?.type === 'running');
+ const track = useTrackAnalytics();
+ const shell = useOptionalShellMode();
+ const shellAgent =
+ shell?.mode.status === 'active' ? { agentId: shell.mode.agentId, agentName: shell.mode.agentName } : {};
const { copy, isCopied } = useActionBarCopy({
copyToClipboard: text => navigator.clipboard.writeText(text),
});
+ const onCopy = () => {
+ track(AnalyticsEvents.Message.COPIED, withSessionProps({ role: 'assistant' }, { sessionId, ...shellAgent }));
+ copy();
+ };
const parts = useAuiState(s => s.message.parts);
@@ -72,7 +85,7 @@ export function AssistantMessageContainer() {
<AssistantMessageBubble
error={error !== undefined ? <MessageErrorBanner message={String(error)} /> : undefined}
actionBar={
- !isThreadRunning ? <MessageActionBar isCopied={isCopied} onCopy={copy} createdAt={createdAt} /> : undefined
+ !isThreadRunning ? <MessageActionBar isCopied={isCopied} onCopy={onCopy} createdAt={createdAt} /> : undefined
}
>
<MessagePrimitive.GroupedParts groupBy={groupBy}>
diff --git a/packages/trueforge-ui/src/containers/ComposerContainer.tsx b/packages/trueforge-ui/src/containers/ComposerContainer.tsx
index b6f98e7aa..de83853c3 100644
--- a/packages/trueforge-ui/src/containers/ComposerContainer.tsx
+++ b/packages/trueforge-ui/src/containers/ComposerContainer.tsx
@@ -4,6 +4,9 @@ import { ComposerPrimitive, useAui, useAuiState } from '@assistant-ui/react';
import { useTrueForgeAgentSpec, useTrueForgeCancel } from '@truefoundry/trueforge-assistant-ui-runtime';
import { useRef, type KeyboardEvent } from 'react';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
+import { withSessionProps } from '../analytics/sessionProps.js';
import { DraftCatalogProvider } from '../atoms/draft/DraftCatalogProvider.js';
import { useComposerBusyState } from '../hooks/useComposerBusyState.js';
import { useComposerPauseView } from '../hooks/useComposerPauseView.js';
@@ -47,8 +50,11 @@ function ComposerBody({
const ComposerShell = useSlot('ComposerShell');
const aui = useAui();
const shell = useOptionalShellMode();
+ const track = useTrackAnalytics();
+ const sessionId = useAuiState(s => s.threadListItem.remoteId);
const hasText = useAuiState(s => s.composer.text.trim().length > 0);
- const hasAttachments = useAuiState(s => s.composer.attachments.length > 0);
+ const attachmentCount = useAuiState(s => s.composer.attachments.length);
+ const hasAttachments = attachmentCount > 0;
const hasContent = hasText || hasAttachments;
const { agentSpec } = useTrueForgeAgentSpec();
// Named (immutable) agents use a server-side model; only draft/mutable composers pick one here.
@@ -61,9 +67,24 @@ function ComposerBody({
// Running/pause no longer lock the input — only session permissions do.
const disabled = !canManageSession;
const canSubmit = canSubmitComposer({ disabled, hasText, hasAttachments, requiresModel, hasModel });
+ const shellAgent =
+ shell?.mode.status === 'active' ? { agentId: shell.mode.agentId, agentName: shell.mode.agentName } : {};
const submit = () => {
if (!canSubmit) return;
// Do not cancelSession here; sendTurn detaches the prior client stream.
+ track(
+ AnalyticsEvents.Message.SENT,
+ withSessionProps(
+ {
+ has_text: hasText,
+ has_attachments: hasAttachments,
+ attachment_count: attachmentCount,
+ requires_model: requiresModel,
+ model: agentSpec?.model?.name,
+ },
+ { sessionId, ...shellAgent },
+ ),
+ );
send(() => aui.composer().send());
};
@@ -86,6 +107,10 @@ function ComposerBody({
onChange={event => {
const files = event.target.files;
if (files) {
+ track(
+ AnalyticsEvents.Attachment.PICKED,
+ withSessionProps({ file_count: files.length }, { sessionId, ...shellAgent }),
+ );
for (const file of files) {
void aui.composer().addAttachment(file);
}
@@ -97,6 +122,15 @@ function ComposerBody({
disabled={disabled}
data-slot="aui_composer-attachment-dropzone"
className="w-full rounded-[0.75rem] transition-[box-shadow] data-[dragging=true]:ring-focus-ring/20 data-[dragging=true]:ring-3"
+ onDropCapture={event => {
+ if (disabled) return;
+ const files = event.dataTransfer?.files;
+ if (files == null || files.length === 0) return;
+ track(
+ AnalyticsEvents.Attachment.PICKED,
+ withSessionProps({ file_count: files.length }, { sessionId, ...shellAgent }),
+ );
+ }}
>
<ComposerPrimitive.Root
data-slot="aui_composer-root"
@@ -134,6 +168,7 @@ function ComposerBody({
onCancel={
canManageSession
? () => {
+ track(AnalyticsEvents.Message.CANCELLED, withSessionProps(undefined, { sessionId, ...shellAgent }));
resetBusy();
void cancel();
}
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/ConnectorSettings.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/ConnectorSettings.tsx
index ebd2a9d30..e9550d426 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/ConnectorSettings.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/ConnectorSettings.tsx
@@ -2,6 +2,8 @@
import { useCallback, useEffect, useMemo, useState, type FormEvent } from 'react';
+import { useTrackAnalytics } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { cn } from '@/atoms/lib/cn.js';
import { auiInputClass } from '@/atoms/lib/inputClasses.js';
import { Button } from '@/atoms/primitives/Button.js';
@@ -30,6 +32,7 @@ type ConnectorsState = {
const ConnectorSettings = () => {
const { connectorCatalog } = useCatalogServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const { handleAuthorize, isOAuthLoading } = useMCPAuth();
const [query, setQuery] = useState('');
@@ -180,6 +183,7 @@ const ConnectorSettings = () => {
void runMutation(async () => {
await createFromCatalog(entry);
+ track(AnalyticsEvents.Settings.CONNECTOR_SAVED, { connector_name: entry.name, mode: 'create' });
}).catch(() => {});
};
@@ -201,6 +205,7 @@ const ConnectorSettings = () => {
toaster?.showSuccess({
title: `${entry.name} connected`,
});
+ track(AnalyticsEvents.Settings.CONNECTOR_SAVED, { connector_name: entry.name, mode: 'create' });
}, 100);
}, setFormError).catch(() => {});
};
@@ -216,12 +221,17 @@ const ConnectorSettings = () => {
}, setFormError);
setTimeout(() => {
toaster?.showSuccess({ title: `${draft.name} ${editingConnector ? 'updated' : 'added'}` });
+ track(AnalyticsEvents.Settings.CONNECTOR_SAVED, {
+ connector_name: draft.name,
+ mode: editingConnector ? 'update' : 'create',
+ });
}, 0);
};
const handleDisconnect = (connector: ConnectorBase) => {
void runMutation(async () => {
await connectorCatalog.disconnectConnector({ id: connector.id });
+ track(AnalyticsEvents.Settings.CONNECTOR_DISCONNECTED, { connector_name: connector.name });
setSelectedConnector(null);
}).catch(() => {});
};
@@ -238,6 +248,7 @@ const ConnectorSettings = () => {
setRemoveError(null);
void runMutation(async () => {
await deleteConnector({ id: connector.id });
+ track(AnalyticsEvents.Settings.CONNECTOR_DELETED, { connector_name: connector.name });
setPendingRemoval(null);
setSelectedConnector(null);
}, setRemoveError).catch(() => {});
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/ModelSettings.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/ModelSettings.tsx
index 85ec5f35a..a239ac21a 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/ModelSettings.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/ModelSettings.tsx
@@ -2,6 +2,8 @@
import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTrackAnalytics } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { Button } from '@/atoms/primitives/Button.js';
import { CatalogLogo } from '@/atoms/primitives/CatalogLogo.js';
import SearchInput from '@/atoms/primitives/SearchInput.js';
@@ -47,6 +49,7 @@ function catalogBaseUrl(provider: ModelProviderCatalogEntry): string {
const ModelSettings = () => {
const { modelCatalog } = useCatalogServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [query, setQuery] = useState('');
const [configured, setConfigured] = useState<ModelProviderBase[]>([]);
@@ -182,6 +185,7 @@ const ModelSettings = () => {
},
err => setKeyError(getErrorMessage(err, 'Request failed')),
);
+ track(AnalyticsEvents.Settings.MODEL_PROVIDER_SAVED, { provider_name: entry.name, mode: 'create' });
};
const handleReplaceKey = async (provider: ModelProviderBase, draft: ModelProviderKeyDraft) => {
@@ -201,6 +205,7 @@ const ModelSettings = () => {
err => setKeyError(getErrorMessage(err, 'Request failed')),
);
toaster?.showSuccess({ title: `${provider.name} updated` });
+ track(AnalyticsEvents.Settings.MODEL_PROVIDER_SAVED, { provider_name: provider.name, mode: 'update' });
};
const closeRemoveDialog = () => {
@@ -243,6 +248,7 @@ const ModelSettings = () => {
if (deleteModelProvider !== undefined) {
removal = runMutation(async () => {
await deleteModelProvider({ id: pending.provider.id });
+ track(AnalyticsEvents.Settings.MODEL_PROVIDER_DELETED, { provider_name: pending.provider.name });
}, reportError);
}
}
@@ -267,6 +273,7 @@ const ModelSettings = () => {
);
setTimeout(() => {
toaster?.showSuccess({ title: `${draft.name} added` });
+ track(AnalyticsEvents.Settings.MODEL_PROVIDER_SAVED, { provider_name: draft.name, mode: 'create' });
}, 0);
};
@@ -293,6 +300,7 @@ const ModelSettings = () => {
title: 'Model provider updated',
description: `${provider.name} was updated successfully.`,
});
+ track(AnalyticsEvents.Settings.MODEL_PROVIDER_SAVED, { provider_name: provider.name, mode: 'update' });
}, 0);
};
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx
index c9959b9c2..a1130174f 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/SandboxSettings.tsx
@@ -2,6 +2,8 @@
import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTrackAnalytics } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { Button } from '../../atoms/primitives/Button.js';
import { Icon } from '../../icons/Icon.js';
import {
@@ -30,6 +32,7 @@ const configFrom = ({
const SandboxSettings = () => {
const { sandboxCatalog } = useCatalogServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [providers, setProviders] = useState<SandboxProviderBase[]>([]);
const [catalog, setCatalog] = useState<SandboxProviderCatalogEntry[]>([]);
@@ -115,6 +118,7 @@ const SandboxSettings = () => {
setCreateEntry(null);
setTimeout(() => {
toaster?.showSuccess({ title: `${createEntry.name} configured` });
+ track(AnalyticsEvents.Settings.SANDBOX_PROVIDER_SAVED, { provider_name: createEntry.name, mode: 'create' });
}, 0);
};
@@ -131,6 +135,7 @@ const SandboxSettings = () => {
setUpdateProvider(null);
setTimeout(() => {
toaster?.showSuccess({ title: `${updateProvider.name} updated` });
+ track(AnalyticsEvents.Settings.SANDBOX_PROVIDER_SAVED, { provider_name: updateProvider.name, mode: 'update' });
}, 0);
};
@@ -146,6 +151,7 @@ const SandboxSettings = () => {
setRemoveError(null);
void runMutation(async () => {
await deleteSandboxProvider({ id: provider.id });
+ track(AnalyticsEvents.Settings.SANDBOX_PROVIDER_DELETED, { provider_name: provider.name });
setPendingRemoval(null);
}, setRemoveError).catch(() => {});
};
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx
index 7551f749c..eeaa607cf 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/SkillSettings.tsx
@@ -2,6 +2,8 @@
import { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { useTrackAnalytics } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { Button } from '@/atoms/primitives/Button.js';
import SearchInput from '@/atoms/primitives/SearchInput.js';
import { Icon } from '@/icons/Icon.js';
@@ -24,6 +26,7 @@ function isManagedSkillError(error: unknown): boolean {
const SkillSettings = () => {
const { skillCatalog } = useCatalogServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [query, setQuery] = useState('');
const [skills, setSkills] = useState<SkillBase[]>([]);
@@ -99,6 +102,7 @@ const SkillSettings = () => {
path: entry.path,
ref: entry.ref,
});
+ track(AnalyticsEvents.Settings.SKILL_IMPORTED, { skill_name: entry.name });
}).catch(() => {});
};
@@ -114,6 +118,7 @@ const SkillSettings = () => {
setRemoveError(null);
void runMutation(async () => {
await deleteSkill({ id: skill.id });
+ track(AnalyticsEvents.Settings.SKILL_DELETED, { skill_name: skill.name });
setPendingRemoval(null);
}, setRemoveError).catch(() => {});
};
@@ -125,6 +130,7 @@ const SkillSettings = () => {
}, setFormError);
setTimeout(() => {
toaster?.showSuccess({ title: `${draft.name} imported` });
+ track(AnalyticsEvents.Settings.SKILL_IMPORTED, { skill_name: draft.name });
}, 0);
};
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/WebSearchSettings.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/WebSearchSettings.tsx
index f96d986f0..de71696b7 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/WebSearchSettings.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/WebSearchSettings.tsx
@@ -2,6 +2,8 @@
import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTrackAnalytics } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { Button } from '../../atoms/primitives/Button.js';
import { Icon } from '../../icons/Icon.js';
import { useCatalogServer } from '../../server/ServerContext.js';
@@ -13,6 +15,7 @@ import ConfigureWebSearchForm, { type WebSearchConfigDraft } from './ConfigureWe
const WebSearchSettings = () => {
const { webSearchCatalog } = useCatalogServer();
const toaster = useToasterOptional();
+ const track = useTrackAnalytics();
const [providers, setProviders] = useState<WebSearchProviderBase[]>([]);
const [catalog, setCatalog] = useState<WebSearchProviderCatalogEntry[]>([]);
@@ -89,6 +92,7 @@ const WebSearchSettings = () => {
setCreateEntry(null);
setTimeout(() => {
toaster?.showSuccess({ title: `${createEntry.name} configured` });
+ track(AnalyticsEvents.Settings.WEB_SEARCH_PROVIDER_SAVED, { provider_name: createEntry.name, mode: 'create' });
}, 0);
};
@@ -104,6 +108,7 @@ const WebSearchSettings = () => {
setUpdateProvider(null);
setTimeout(() => {
toaster?.showSuccess({ title: `${updateProvider.name} updated` });
+ track(AnalyticsEvents.Settings.WEB_SEARCH_PROVIDER_SAVED, { provider_name: updateProvider.name, mode: 'update' });
}, 0);
};
diff --git a/packages/trueforge-ui/src/containers/SettingsBuilder/index.tsx b/packages/trueforge-ui/src/containers/SettingsBuilder/index.tsx
index b16dbd05e..dd97012f9 100644
--- a/packages/trueforge-ui/src/containers/SettingsBuilder/index.tsx
+++ b/packages/trueforge-ui/src/containers/SettingsBuilder/index.tsx
@@ -2,6 +2,9 @@
import { lazy, Suspense, useCallback, useEffect, useMemo, type ReactNode } from 'react';
+import { useTrackAnalytics } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
+
import { useDraftCatalog } from '@/atoms/draft/DraftCatalogProvider.js';
import { auiButtonClass } from '@/atoms/lib/buttonClasses.js';
import { cn } from '@/atoms/lib/cn.js';
@@ -34,6 +37,7 @@ const TruefoundrySettingsBuilder = ({ headerStart }: { headerStart?: ReactNode }
const { settingsOpen, settingsSection: section, setSettingsOpen } = useShellMode();
const catalog = useOptionalCatalogServer();
const refreshServerCapabilities = useOptionalRefreshServerCapabilities();
+ const track = useTrackAnalytics();
const { refresh: refreshDraftCatalog } = useDraftCatalog();
// dock/widget panels are ~mobile width even on a wide viewport — keep Settings stacked.
// SidebarLayout mobile is not under CompactLayoutProvider, so treat it the same.
@@ -45,8 +49,9 @@ const TruefoundrySettingsBuilder = ({ headerStart }: { headerStart?: ReactNode }
const hasWebSearch = catalog?.webSearchCatalog != null;
const closeSettings = useCallback(() => {
+ track(AnalyticsEvents.Settings.CLOSED, { section });
setSettingsOpen(false);
- }, [setSettingsOpen]);
+ }, [section, setSettingsOpen, track]);
// Refresh catalogs whenever settings are closed or navigated away from.
useEffect(() => {
@@ -157,6 +162,7 @@ const TruefoundrySettingsBuilder = ({ headerStart }: { headerStart?: ReactNode }
: 'text-text-secondary hover:bg-ghost-button-hover/60 hover:text-text-primary',
)}
onClick={() => {
+ track(AnalyticsEvents.Settings.SECTION_CHANGED, { section: item.id });
setSettingsOpen(true, item.id);
}}
>
diff --git a/packages/trueforge-ui/src/containers/ThreadListContainer.tsx b/packages/trueforge-ui/src/containers/ThreadListContainer.tsx
index 55402e2be..3a395082c 100644
--- a/packages/trueforge-ui/src/containers/ThreadListContainer.tsx
+++ b/packages/trueforge-ui/src/containers/ThreadListContainer.tsx
@@ -10,6 +10,9 @@ import {
} from '@assistant-ui/react';
import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode, type Ref } from 'react';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
+import { withSessionProps } from '../analytics/sessionProps.js';
import { AgentHistoryFilterButton } from '../atoms/AgentHistoryFilterButton.js';
import { auiButtonClass } from '../atoms/lib/buttonClasses.js';
import { cn } from '../atoms/lib/cn.js';
@@ -61,12 +64,14 @@ function ThreadListItemActionsMenu({
canDelete,
deleteDisabled,
onRename,
+ onDelete,
}: {
canRename: boolean;
renameDisabled: boolean;
canDelete: boolean;
deleteDisabled: boolean;
onRename: () => void;
+ onDelete: () => void;
}) {
const PermissionGuard = useSlot('PermissionGuard');
const compact = useCompactLayout();
@@ -108,7 +113,9 @@ function ThreadListItemActionsMenu({
<ThreadListItemPrimitive.Delete
className={deleteItemClass}
onClick={() => {
- if (!deleteDisabled) setSheetOpen(false);
+ if (deleteDisabled) return;
+ setSheetOpen(false);
+ onDelete();
}}
>
<Icon name="trash" className="size-3.5" />
@@ -181,6 +188,7 @@ function ThreadListItemRow({
}) {
const aui = useAui();
const shell = useOptionalShellMode();
+ const track = useTrackAnalytics();
const toaster = useToasterOptional();
const ThreadListRow = useSlot('ThreadListRow');
const id = useAuiState(s => s.threadListItem.id);
@@ -213,6 +221,7 @@ function ThreadListItemRow({
setRenameSaving(true);
try {
await aui.threadListItem().rename(trimmed);
+ track(AnalyticsEvents.Session.RENAMED, withSessionProps(undefined, { sessionId: remoteId, agentName }));
setRenameOpen(false);
} catch (caught) {
toaster?.showError(caught);
@@ -229,6 +238,10 @@ function ThreadListItemRow({
agentName={agentName}
lastMessageAt={lastMessageAt}
onSelect={() => {
+ track(
+ AnalyticsEvents.Session.SELECTED,
+ withSessionProps({ is_mutable: threadListItemIsMutable(custom) }, { sessionId: remoteId, agentName }),
+ );
onThreadOpen?.();
shell?.setSettingsOpen(false);
shell?.setLibraryOpen(false);
@@ -277,6 +290,9 @@ function ThreadListItemRow({
canDelete={showDelete}
deleteDisabled={deleteDisabled}
onRename={() => setRenameOpen(true)}
+ onDelete={() => {
+ track(AnalyticsEvents.Session.DELETED, withSessionProps(undefined, { sessionId: remoteId, agentName }));
+ }}
/>
) : undefined
}
@@ -406,6 +422,7 @@ function RecentChatsSection({
export function ThreadListContainer({ onThreadOpen, variant = 'default' }: ThreadListContainerProps = {}) {
const aui = useAui();
const server = useOptionalServer();
+ const track = useTrackAnalytics();
const isLoading = useAuiState(s => s.threads.isLoading);
const isLoadingMore = useAuiState(s => s.threads.isLoadingMore);
const hasMore = useAuiState(s => s.threads.hasMore);
@@ -482,6 +499,16 @@ export function ThreadListContainer({ onThreadOpen, variant = 'default' }: Threa
}, [hasMore, isIdle, isLoading, isLoadingMore, threadIds.length]);
const handleNewChat = () => {
+ // No session_id yet — attaching the prior thread's id would mis-join new-chat funnels.
+ track(
+ AnalyticsEvents.Session.NEW,
+ withSessionProps(
+ { is_composer_enabled: shell?.isComposerEnabled === true },
+ {
+ ...(shell?.mode.status === 'active' ? { agentId: shell.mode.agentId, agentName: shell.mode.agentName } : {}),
+ },
+ ),
+ );
onThreadOpen?.();
shell?.setLibraryOpen(false);
shell?.setSessionsOpen(false);
diff --git a/packages/trueforge-ui/src/containers/ToolCallContainer.tsx b/packages/trueforge-ui/src/containers/ToolCallContainer.tsx
index 4dff89780..e47807746 100644
--- a/packages/trueforge-ui/src/containers/ToolCallContainer.tsx
+++ b/packages/trueforge-ui/src/containers/ToolCallContainer.tsx
@@ -11,6 +11,8 @@ import {
import { useTrueForgeRespondToToolApproval } from '@truefoundry/trueforge-assistant-ui-runtime';
import { useCallback, useState } from 'react';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
import { useSlot } from '../theme/SlotsProvider.js';
import {
ASK_USER_TOOL_NAME,
@@ -62,6 +64,8 @@ function NestedSubAgentAssistantMessage() {
function ToolApprovalSlot({ part }: { part: ToolCallMessagePartProps }) {
const isNestedReadonly = useNestedApprovalBridge();
const respondToNestedApproval = useTrueForgeRespondToToolApproval();
+ // Fire here (not the bar atom) so nested + optionId/approved mapping stay correct.
+ const track = useTrackAnalytics();
const respond = (response: ToolApprovalResponse) => {
if (!isNestedReadonly) {
@@ -93,6 +97,16 @@ function ToolApprovalSlot({ part }: { part: ToolCallMessagePartProps }) {
};
const onSelectOption = (optionId: string, reason?: string) => {
+ const options = buildApprovalOptions(part.approval?.options);
+ const option = options.find(o => o.id === optionId);
+ const approved = optionId === '__allow' ? true : optionId === '__deny' ? false : option?.isAllow;
+ track(AnalyticsEvents.Tool.APPROVAL_RESOLVED, {
+ tool_name: part.toolName,
+ option_id: optionId,
+ approved,
+ has_reason: reason != null && reason.trim().length > 0,
+ nested: isNestedReadonly,
+ });
if (optionId === '__allow') return respond({ approved: true });
if (optionId === '__deny') return respond({ approved: false, reason });
return respond({ optionId, reason });
diff --git a/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx b/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx
index c8993663c..fd610dc4d 100644
--- a/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx
+++ b/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx
@@ -7,6 +7,8 @@ import type {
import { lazy, Suspense, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
import { ThinkingOrb } from 'thinking-orbs';
+import { AnalyticsProvider } from '../analytics/AnalyticsProvider.js';
+import type { AnalyticsConfig } from '../analytics/types.js';
import { AgentConfigInstructionsProvider } from '../atoms/draft/AgentConfigInstructionsContext.js';
import { DraftCatalogProvider } from '../atoms/draft/DraftCatalogProvider.js';
import { DraftSpecPreferenceBridge } from '../atoms/draft/DraftSpecPreferenceBridge.js';
@@ -53,6 +55,8 @@ export type TrueForgeUIProps = {
initialSessionId?: string;
adapters?: RuntimeAdapters;
onError?: (error: unknown) => void;
+ /** Host product-analytics sink; SDK never ships a vendor. */
+ analytics?: AnalyticsConfig;
/**
* Agent / library / composer shell mode.
* Defaults to `{ mode: "AgentLibraryWithComposer" }`.
@@ -284,6 +288,7 @@ export function TrueForgeUIShell(props: TrueForgeUIShellProps) {
initialSettingsOpen = false,
server: serverConfig,
onError,
+ analytics,
customActionRenderers,
currentUser,
resolvedRoutes,
@@ -321,31 +326,33 @@ export function TrueForgeUIShell(props: TrueForgeUIShellProps) {
// Outer toaster so ShellRouteSync (sibling of chat provider) can toast access-denied
// deep links; nested ToasterProvider inside TrueForgeChatProvider stays for hosts
- // that mount chat alone.
+ // that mount chat alone. Analytics wraps the same tree so chrome + chat share one sink.
const shellTree = (
- <ToasterProvider>
- <ShellModeProvider agentConfig={agentConfig} initialSettingsOpen={initialSettingsOpen}>
- <LibrarySessionShareBoot />
- {resolvedRoutes != null ? (
- <Suspense fallback={null}>
- <ShellRouteSync
- routes={resolvedRoutes}
- activeRemoteId={activeRemoteId}
- initialSettingsOpen={initialSettingsOpen}
- onError={onError}
- />
- </Suspense>
- ) : null}
- <ChatProviderFromShell
- server={server}
- onError={onError}
- onRemoteIdChange={resolvedRoutes != null ? handleRemoteIdChange : undefined}
- {...providerRest}
- >
- {layoutTree}
- </ChatProviderFromShell>
- </ShellModeProvider>
- </ToasterProvider>
+ <AnalyticsProvider track={analytics?.track}>
+ <ToasterProvider>
+ <ShellModeProvider agentConfig={agentConfig} initialSettingsOpen={initialSettingsOpen}>
+ <LibrarySessionShareBoot />
+ {resolvedRoutes != null ? (
+ <Suspense fallback={null}>
+ <ShellRouteSync
+ routes={resolvedRoutes}
+ activeRemoteId={activeRemoteId}
+ initialSettingsOpen={initialSettingsOpen}
+ onError={onError}
+ />
+ </Suspense>
+ ) : null}
+ <ChatProviderFromShell
+ server={server}
+ onError={onError}
+ onRemoteIdChange={resolvedRoutes != null ? handleRemoteIdChange : undefined}
+ {...providerRest}
+ >
+ {layoutTree}
+ </ChatProviderFromShell>
+ </ShellModeProvider>
+ </ToasterProvider>
+ </AnalyticsProvider>
);
// Widget visibility provider is used to control the visibility of the widget with isolated state
const visibilityTree =
diff --git a/packages/trueforge-ui/src/containers/UserMessageContainer.tsx b/packages/trueforge-ui/src/containers/UserMessageContainer.tsx
index b85752019..96c1aa104 100644
--- a/packages/trueforge-ui/src/containers/UserMessageContainer.tsx
+++ b/packages/trueforge-ui/src/containers/UserMessageContainer.tsx
@@ -3,7 +3,11 @@
import { useActionBarCopy, useActionBarEdit, useThreadIsRunning } from '@assistant-ui/core/react';
import { MessagePrimitive, useAui, useAuiState } from '@assistant-ui/react';
+import { useTrackAnalytics } from '../analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '../analytics/events.js';
+import { withSessionProps } from '../analytics/sessionProps.js';
import { useActiveSessionCanManage } from '../hooks/useResourcePermissions.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
import { useSlot } from '../theme/SlotsProvider.js';
import { MessageAttachmentsContainer } from './AttachmentsContainer.js';
@@ -13,7 +17,10 @@ export function UserMessageContainer() {
const isRunning = useThreadIsRunning();
const canManageSession = useActiveSessionCanManage();
const aui = useAui();
+ const track = useTrackAnalytics();
+ const shell = useOptionalShellMode();
const createdAt = useAuiState(s => s.message.createdAt);
+ const sessionId = useAuiState(s => s.threadListItem.remoteId);
const text = useAuiState(s =>
s.message.content
.filter((part): part is { type: 'text'; text: string } => part.type === 'text')
@@ -24,6 +31,9 @@ export function UserMessageContainer() {
const { copy, isCopied } = useActionBarCopy({
copyToClipboard: value => navigator.clipboard.writeText(value),
});
+ const shellAgent =
+ shell?.mode.status === 'active' ? { agentId: shell.mode.agentId, agentName: shell.mode.agentName } : {};
+ const sessionProps = { sessionId, ...shellAgent };
return (
<MessagePrimitive.Root data-role="user">
@@ -37,10 +47,17 @@ export function UserMessageContainer() {
editDisabled={editDisabled || !canManageSession}
retryDisabled={!canManageSession}
createdAt={createdAt}
- onCopy={copy}
- onEdit={edit}
+ onCopy={() => {
+ track(AnalyticsEvents.Message.COPIED, withSessionProps({ role: 'user' }, sessionProps));
+ copy();
+ }}
+ onEdit={() => {
+ track(AnalyticsEvents.Message.EDIT_STARTED, withSessionProps(undefined, sessionProps));
+ edit();
+ }}
onRetry={() => {
if (!canManageSession) return;
+ track(AnalyticsEvents.Message.RETRIED, withSessionProps(undefined, sessionProps));
aui.message().composer().beginEdit();
aui.message().composer().send({ startRun: true });
}}
diff --git a/packages/trueforge-ui/src/index.ts b/packages/trueforge-ui/src/index.ts
index 8d0731e30..8a801f0c3 100644
--- a/packages/trueforge-ui/src/index.ts
+++ b/packages/trueforge-ui/src/index.ts
@@ -145,6 +145,8 @@ export type { UserMessageEditProps } from './atoms/UserMessageEdit.js';
export { WelcomeScreen } from './atoms/WelcomeScreen.js';
export type { WelcomeScreenProps } from './atoms/WelcomeScreen.js';
+export { AnalyticsEvents, AnalyticsProvider, useTrackAnalytics, withSessionProps } from './analytics/index.js';
+export type { AnalyticsConfig, AnalyticsEventProps, TrackAnalytics } from './analytics/index.js';
export { AgentStepsCard } from './atoms/adapters/AgentStepsCardAdapter.js';
export type { AgentStepsCardProps } from './atoms/adapters/AgentStepsCardAdapter.js';
export type {
diff --git a/packages/trueforge-ui/test/analytics/AnalyticsProvider.test.tsx b/packages/trueforge-ui/test/analytics/AnalyticsProvider.test.tsx
new file mode 100644
index 000000000..1d4c1fed6
--- /dev/null
+++ b/packages/trueforge-ui/test/analytics/AnalyticsProvider.test.tsx
@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+import { renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AnalyticsProvider, useTrackAnalytics } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
+import { withSessionProps } from '@/analytics/sessionProps.js';
+
+describe('AnalyticsProvider', () => {
+ it('no-ops when no provider is mounted', () => {
+ const { result } = renderHook(() => useTrackAnalytics());
+ expect(() => result.current(AnalyticsEvents.Message.SENT)).not.toThrow();
+ });
+
+ it('forwards event name and props to the host track sink', () => {
+ const track = vi.fn();
+ const wrapper = ({ children }: { children: ReactNode }) => (
+ <AnalyticsProvider track={track}>{children}</AnalyticsProvider>
+ );
+
+ const { result } = renderHook(() => useTrackAnalytics(), { wrapper });
+ result.current(AnalyticsEvents.Message.SENT, { has_text: true });
+
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Message.SENT, { has_text: true });
+ });
+
+ it('does not throw when the host track sink throws', () => {
+ const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+ const track = vi.fn(() => {
+ throw new Error('sink down');
+ });
+ const wrapper = ({ children }: { children: ReactNode }) => (
+ <AnalyticsProvider track={track}>{children}</AnalyticsProvider>
+ );
+
+ const { result } = renderHook(() => useTrackAnalytics(), { wrapper });
+
+ expect(() => result.current(AnalyticsEvents.Message.SENT)).not.toThrow();
+ expect(consoleError).toHaveBeenCalled();
+ consoleError.mockRestore();
+ });
+});
+
+describe('withSessionProps', () => {
+ it('merges only defined session identity fields', () => {
+ expect(withSessionProps({ has_text: true }, { sessionId: 's1', agentId: '', agentName: 'bot' })).toEqual({
+ has_text: true,
+ session_id: 's1',
+ agent_name: 'bot',
+ });
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
index 16cbd8bde..5bcaecbec 100644
--- a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
+++ b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
@@ -4,6 +4,8 @@ import type { ReactNode } from 'react';
import { useEffect } from 'react';
import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { AgentsLibrary } from '@/atoms/AgentsLibrary.js';
import { AgentsLibraryButton } from '@/atoms/AgentsLibraryButton.js';
import { CenteredModal } from '@/atoms/primitives/CenteredModal.js';
@@ -80,18 +82,21 @@ function renderLibrary(
{
server = mockServer(),
agentConfig,
+ track,
}: {
server?: AgentUIServer;
agentConfig?: Parameters<typeof ShellModeProvider>[0]['agentConfig'];
+ track?: (eventName: string, data?: Record<string, string | number | boolean | undefined>) => void;
} = {},
) {
- return render(
+ const tree = (
<SlotsProvider>
<ServerProvider server={server}>
<ShellModeProvider agentConfig={agentConfig}>{ui}</ShellModeProvider>
</ServerProvider>
- </SlotsProvider>,
+ </SlotsProvider>
);
+ return render(track != null ? <AnalyticsProvider track={track}>{tree}</AnalyticsProvider> : tree);
}
function LibraryHarness({ children, onSelectAgent }: { children?: ReactNode; onSelectAgent?: (name: string) => void }) {
@@ -193,8 +198,9 @@ describe('AgentsLibrary', () => {
{ name: 'beta-agent', agentId: 'beta-agent' },
]);
const onSelectAgent = vi.fn();
+ const track = vi.fn();
- renderLibrary(<LibraryHarness onSelectAgent={onSelectAgent} />, { server });
+ renderLibrary(<LibraryHarness onSelectAgent={onSelectAgent} />, { server, track });
fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
expect(screen.getByRole('heading', { name: 'Agents' })).toBeInTheDocument();
@@ -205,6 +211,11 @@ describe('AgentsLibrary', () => {
fireEvent.click(screen.getByRole('button', { name: 'Try agent beta-agent' }));
expect(onSelectAgent).toHaveBeenCalledWith('beta-agent');
+ expect(track).toHaveBeenCalledWith(
+ AnalyticsEvents.Library.AGENT_TRIED,
+ expect.objectContaining({ agent_id: 'beta-agent', agent_name: 'beta-agent' }),
+ );
+ expect(track.mock.calls.some(call => call[0] === AnalyticsEvents.Library.CLOSED)).toBe(false);
await waitFor(() => {
expect(screen.queryByRole('heading', { name: 'Agents' })).not.toBeInTheDocument();
});
@@ -603,31 +614,37 @@ describe('AgentsLibrary', () => {
});
it('closes via Escape', () => {
- renderLibrary(<LibraryHarness />);
+ const track = vi.fn();
+ renderLibrary(<LibraryHarness />, { track });
fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
expect(screen.getByRole('heading', { name: 'Agents' })).toBeInTheDocument();
fireEvent.keyDown(window, { key: 'Escape' });
expect(screen.queryByRole('heading', { name: 'Agents' })).not.toBeInTheDocument();
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Library.CLOSED, undefined);
});
});
describe('AgentsLibraryButton', () => {
it('opens the Agents panel from the trigger', async () => {
const server = mockServer([{ name: 'alpha-agent', agentId: 'alpha-agent' }]);
+ const track = vi.fn();
renderLibrary(
<>
<AgentsLibraryButton />
<AgentsLibrary />
</>,
- { server },
+ { server, track },
);
fireEvent.click(screen.getByRole('button', { name: /Agents/ }));
expect(screen.getByRole('heading', { name: 'Agents' })).toBeInTheDocument();
expect(screen.getByRole('button', { name: /Agents/ })).toHaveAttribute('aria-current', 'page');
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Library.OPENED, undefined);
+ fireEvent.click(screen.getByRole('button', { name: /Agents/ }));
+ expect(track).toHaveBeenCalledTimes(1);
await waitFor(() => {
expect(screen.getByRole('button', { name: 'Try agent alpha-agent' })).toBeInTheDocument();
});
diff --git a/packages/trueforge-ui/test/atoms/environments/EnvironmentFormDrawer.test.tsx b/packages/trueforge-ui/test/atoms/environments/EnvironmentFormDrawer.test.tsx
index 77664c3c8..ce333b97f 100644
--- a/packages/trueforge-ui/test/atoms/environments/EnvironmentFormDrawer.test.tsx
+++ b/packages/trueforge-ui/test/atoms/environments/EnvironmentFormDrawer.test.tsx
@@ -2,6 +2,9 @@
import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
+import type { TrackAnalytics } from '@/analytics/types.js';
import { EnvironmentFormDrawer } from '@/atoms/environments/EnvironmentFormDrawer.js';
import { ToasterProvider } from '@/containers/ToasterContainer.js';
import { ServerProvider } from '@/server/ServerContext.js';
@@ -61,11 +64,13 @@ function renderDrawer({
environment,
environmentOverrides = {},
onSaved = vi.fn(),
+ track,
}: {
mode?: 'create' | 'edit';
environment?: SandboxEnvironment;
environmentOverrides?: Partial<SandboxEnvironmentServer>;
onSaved?: () => void;
+ track?: TrackAnalytics;
} = {}) {
const createOrUpdateEnvironment = vi.fn(async ({ manifest }) => ({
id: 'e1',
@@ -89,7 +94,7 @@ function renderDrawer({
const server = createMockAgentUIServer({ sandboxEnvironments: environmentServer });
const onOpenChange = vi.fn();
- render(
+ const tree = (
<ServerProvider server={server}>
<ToasterProvider>
<EnvironmentFormDrawer
@@ -100,15 +105,17 @@ function renderDrawer({
onSaved={onSaved}
/>
</ToasterProvider>
- </ServerProvider>,
+ </ServerProvider>
);
+ render(track != null ? <AnalyticsProvider track={track}>{tree}</AnalyticsProvider> : tree);
- return { createOrUpdateEnvironment, onOpenChange, onSaved };
+ return { createOrUpdateEnvironment, onOpenChange, onSaved, track };
}
describe('EnvironmentFormDrawer', () => {
it('saves UI form values', async () => {
- const { createOrUpdateEnvironment, onSaved } = renderDrawer();
+ const track = vi.fn();
+ const { createOrUpdateEnvironment, onSaved } = renderDrawer({ track });
expect(screen.queryByRole('button', { name: 'YAML' })).not.toBeInTheDocument();
const nameInput = screen.getByPlaceholderText('my-environment');
fireEvent.change(nameInput, { target: { value: 'node-web' } });
@@ -118,6 +125,10 @@ describe('EnvironmentFormDrawer', () => {
});
expect(createOrUpdateEnvironment.mock.calls[0]?.[0]?.manifest.name).toBe('node-web');
expect(onSaved).toHaveBeenCalled();
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Environment.CREATED, {
+ environment_name: 'node-web',
+ environment_id: 'e1',
+ });
});
it('confirms when switching modes while dirty in edit', async () => {
diff --git a/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx b/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx
index 53f47a818..2c8473c1c 100644
--- a/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx
+++ b/packages/trueforge-ui/test/atoms/environments/EnvironmentsPage.test.tsx
@@ -1,7 +1,11 @@
// @vitest-environment jsdom
-import { act, render, screen, waitFor } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
+import type { TrackAnalytics } from '@/analytics/types.js';
+import { EnvironmentsButton } from '@/atoms/EnvironmentsButton.js';
import { EnvironmentsPage, PENDING_ENVIRONMENTS_POLL_INTERVAL_MS } from '@/atoms/environments/EnvironmentsPage.js';
import { ToasterProvider } from '@/containers/ToasterContainer.js';
import { ServerProvider } from '@/server/ServerContext.js';
@@ -41,19 +45,13 @@ const originalClose = Object.getOwnPropertyDescriptor(HTMLDialogElement.prototyp
beforeEach(() => {
window.history.replaceState(null, '', '/environments');
- Object.defineProperty(HTMLDialogElement.prototype, 'showModal', {
- configurable: true,
- value: function showModal(this: HTMLDialogElement) {
- this.open = true;
- },
- });
- Object.defineProperty(HTMLDialogElement.prototype, 'close', {
- configurable: true,
- value: function close(this: HTMLDialogElement) {
- this.open = false;
- this.dispatchEvent(new Event('close'));
- },
- });
+ HTMLDialogElement.prototype.showModal = function showModal() {
+ this.open = true;
+ };
+ HTMLDialogElement.prototype.close = function close() {
+ this.open = false;
+ this.dispatchEvent(new Event('close'));
+ };
});
afterEach(() => {
@@ -73,9 +71,11 @@ afterEach(() => {
function renderPage({
environments = sampleEnvironments,
environmentOverrides = {},
+ track,
}: {
environments?: SandboxEnvironment[];
environmentOverrides?: Partial<SandboxEnvironmentServer>;
+ track?: TrackAnalytics;
} = {}) {
const environmentServer = createMockSandboxEnvironmentServer({
listEnvironments: vi.fn(async () => ({ data: environments })),
@@ -86,15 +86,16 @@ function renderPage({
sandboxEnvironments: environmentServer,
});
- return render(
+ const tree = (
<ServerProvider server={server}>
<ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
<ToasterProvider>
<EnvironmentsPage />
</ToasterProvider>
</ShellModeProvider>
- </ServerProvider>,
+ </ServerProvider>
);
+ return render(track != null ? <AnalyticsProvider track={track}>{tree}</AnalyticsProvider> : tree);
}
describe('EnvironmentsPage', () => {
@@ -209,4 +210,55 @@ describe('EnvironmentsPage', () => {
});
expect(listSandboxProviders).not.toHaveBeenCalled();
});
+
+ it('tracks environment deleted after confirm', async () => {
+ const deleteEnvironment = vi.fn(async () => {});
+ const track = vi.fn();
+ renderPage({ environmentOverrides: { deleteEnvironment }, track });
+ await waitFor(() => {
+ expect(screen.getByText('python-data')).toBeInTheDocument();
+ });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Delete python-data' }));
+ const dialog = screen.getByRole('dialog');
+ Object.defineProperty(dialog, 'close', {
+ configurable: true,
+ value() {
+ (this as HTMLDialogElement).open = false;
+ this.dispatchEvent(new Event('close'));
+ },
+ });
+ fireEvent.click(within(dialog).getByRole('button', { name: 'Delete' }));
+
+ await waitFor(() => expect(deleteEnvironment).toHaveBeenCalledWith({ name: 'python-data' }));
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Environment.DELETED, {
+ environment_name: 'python-data',
+ environment_id: 'e1',
+ });
+ });
+});
+
+describe('EnvironmentsButton', () => {
+ it('tracks page opened when opening environments', () => {
+ const track = vi.fn();
+ const server = createMockAgentUIServer({
+ catalog: createMockCatalog(),
+ sandboxEnvironments: createMockSandboxEnvironmentServer(),
+ });
+
+ render(
+ <AnalyticsProvider track={track}>
+ <ServerProvider server={server}>
+ <ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
+ <EnvironmentsButton />
+ </ShellModeProvider>
+ </ServerProvider>
+ </AnalyticsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Environments' }));
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Environment.PAGE_OPENED, undefined);
+ fireEvent.click(screen.getByRole('button', { name: 'Environments' }));
+ expect(track).toHaveBeenCalledTimes(1);
+ });
});
diff --git a/packages/trueforge-ui/test/atoms/schedules/ScheduleFormDrawer.test.tsx b/packages/trueforge-ui/test/atoms/schedules/ScheduleFormDrawer.test.tsx
index 17f53d274..5df37623f 100644
--- a/packages/trueforge-ui/test/atoms/schedules/ScheduleFormDrawer.test.tsx
+++ b/packages/trueforge-ui/test/atoms/schedules/ScheduleFormDrawer.test.tsx
@@ -3,6 +3,8 @@ import { fireEvent, render, screen, waitFor, within } from '@testing-library/rea
import type { ComponentProps } from 'react';
import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { ScheduleFormDrawer } from '@/atoms/schedules/ScheduleFormDrawer.js';
import { ToasterProvider } from '@/containers/ToasterContainer.js';
import { ServerProvider } from '@/server/ServerContext.js';
@@ -92,12 +94,14 @@ function renderDrawer({
scheduleServer,
permissions,
withShell = false,
+ track,
...props
}: Partial<ComponentProps<typeof ScheduleFormDrawer>> & {
server?: AgentUIServer;
scheduleServer?: ScheduleServer;
permissions?: PermissionsServer;
withShell?: boolean;
+ track?: (eventName: string, data?: Record<string, string | number | boolean | undefined>) => void;
}) {
const agentServer =
server ??
@@ -130,24 +134,25 @@ function renderDrawer({
});
const schedules = scheduleServer ?? mockScheduleServer();
const drawer = <ScheduleFormDrawer open mode="create" onOpenChange={() => undefined} {...props} />;
+ const tree = (
+ <SlotsProvider>
+ <ToasterProvider>
+ <ServerProvider server={{ ...agentServer, schedules, ...(permissions == null ? {} : { permissions }) }}>
+ {withShell ? (
+ <ShellModeProvider>
+ {drawer}
+ <AgentBuilderProbe />
+ </ShellModeProvider>
+ ) : (
+ drawer
+ )}
+ </ServerProvider>
+ </ToasterProvider>
+ </SlotsProvider>
+ );
return {
schedules,
- ...render(
- <SlotsProvider>
- <ToasterProvider>
- <ServerProvider server={{ ...agentServer, schedules, ...(permissions == null ? {} : { permissions }) }}>
- {withShell ? (
- <ShellModeProvider>
- {drawer}
- <AgentBuilderProbe />
- </ShellModeProvider>
- ) : (
- drawer
- )}
- </ServerProvider>
- </ToasterProvider>
- </SlotsProvider>,
- ),
+ ...render(track != null ? <AnalyticsProvider track={track}>{tree}</AnalyticsProvider> : tree),
};
}
@@ -337,9 +342,11 @@ describe('ScheduleFormDrawer', () => {
status: req.status,
}),
);
+ const track = vi.fn();
renderDrawer({
scheduleServer: mockScheduleServer({ createSchedule, updateSchedule }),
initialAgentId: 'demo-agent',
+ track,
});
await saveCreateForm();
@@ -357,6 +364,10 @@ describe('ScheduleFormDrawer', () => {
);
});
expect(createSchedule).toHaveBeenCalledTimes(1);
+ expect(track).toHaveBeenCalledWith(
+ AnalyticsEvents.Schedule.EDITED,
+ expect.objectContaining({ schedule_id: 'new', agent_id: 'demo-agent' }),
+ );
expect(await screen.findByRole('heading', { name: 'Test Schedule' })).toBeInTheDocument();
expect(screen.getByText('digest-v2')).toBeInTheDocument();
});
diff --git a/packages/trueforge-ui/test/containers/ComposerContainer.test.tsx b/packages/trueforge-ui/test/containers/ComposerContainer.test.tsx
index 052005f63..54300185c 100644
--- a/packages/trueforge-ui/test/containers/ComposerContainer.test.tsx
+++ b/packages/trueforge-ui/test/containers/ComposerContainer.test.tsx
@@ -3,6 +3,8 @@ import type { AppendMessage } from '@assistant-ui/react';
import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import { canSubmitComposer, ComposerContainer } from '@/containers/ComposerContainer.js';
import { ComposerBusyProvider } from '@/hooks/useComposerBusyState.js';
import {
@@ -188,6 +190,62 @@ describe('ComposerContainer', () => {
expect(onNew).toHaveBeenCalledTimes(1);
});
+ it('tracks message_sent when the host supplies analytics.track', async () => {
+ const track = vi.fn();
+ const onNew = vi.fn(async () => {});
+ render(
+ <AnalyticsProvider track={track}>
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'support' }}>
+ <RuntimeHarness messages={[]} onNew={onNew}>
+ <ComposerBusyProvider>
+ <ComposerContainer />
+ </ComposerBusyProvider>
+ </RuntimeHarness>
+ </ShellModeProvider>
+ </AnalyticsProvider>,
+ );
+ const input = screen.getByRole<HTMLTextAreaElement>('textbox', { name: 'Message input' });
+
+ fireEvent.change(input, { target: { value: 'hi' } });
+ fireEvent.keyDown(input, { key: 'Enter' });
+ await waitFor(() => expect(onNew).toHaveBeenCalledTimes(1));
+ expect(track).toHaveBeenCalledWith(
+ AnalyticsEvents.Message.SENT,
+ expect.objectContaining({ has_text: true, agent_name: 'support' }),
+ );
+ });
+
+ it('tracks attachment_picked on dropzone drop', () => {
+ const track = vi.fn();
+ render(
+ <AnalyticsProvider track={track}>
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'support' }}>
+ <RuntimeHarness messages={[]}>
+ <ComposerBusyProvider>
+ <ComposerContainer />
+ </ComposerBusyProvider>
+ </RuntimeHarness>
+ </ShellModeProvider>
+ </AnalyticsProvider>,
+ );
+ const dropzone = document.querySelector('[data-slot="aui_composer-attachment-dropzone"]');
+ expect(dropzone).not.toBeNull();
+ if (dropzone === null) {
+ throw new Error('Expected attachment dropzone');
+ }
+
+ fireEvent.drop(dropzone, {
+ dataTransfer: {
+ files: [new File(['hello'], 'note.txt', { type: 'text/plain' })],
+ },
+ });
+
+ expect(track).toHaveBeenCalledWith(
+ AnalyticsEvents.Attachment.PICKED,
+ expect.objectContaining({ file_count: 1, agent_name: 'support' }),
+ );
+ });
+
it('preserves consumer section overrides in draft mode', () => {
render(
<SlotsProvider
diff --git a/packages/trueforge-ui/test/containers/SettingsBuilder/ConnectorSettings.test.tsx b/packages/trueforge-ui/test/containers/SettingsBuilder/ConnectorSettings.test.tsx
index a71e76baf..1fc278caa 100644
--- a/packages/trueforge-ui/test/containers/SettingsBuilder/ConnectorSettings.test.tsx
+++ b/packages/trueforge-ui/test/containers/SettingsBuilder/ConnectorSettings.test.tsx
@@ -2,9 +2,11 @@
import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import ConnectorSettings from '@/containers/SettingsBuilder/ConnectorSettings.js';
import { ServerProvider } from '@/server/ServerContext.js';
-import type { ConnectorBase } from '@/server/types.js';
+import type { ConnectorBase, ConnectorCatalogEntry } from '@/server/types.js';
import { createMockAgentUIServer, createMockCatalog } from '../../server/mockServer.js';
beforeAll(() => {
@@ -108,4 +110,153 @@ describe('ConnectorSettings edit flow', () => {
await waitFor(() => expect(deleteConnector).toHaveBeenCalledWith({ id: connector.id }));
});
+
+ it('tracks connector saved after a none-auth catalog connect', async () => {
+ const catalogEntry: ConnectorCatalogEntry = {
+ id: 'cat-public',
+ name: 'Public MCP',
+ description: 'No auth',
+ url: 'https://mcp.example.com/mcp',
+ auth: { type: 'none' },
+ };
+ const created: ConnectorBase = {
+ id: 'public-mcp',
+ name: catalogEntry.name,
+ description: catalogEntry.description ?? catalogEntry.url,
+ url: catalogEntry.url,
+ authenticated: true,
+ requiresAuth: false,
+ auth: { type: 'none' },
+ };
+ const createConnector = vi.fn(async () => created);
+ const track = vi.fn();
+ const server = createMockAgentUIServer({
+ catalog: createMockCatalog({
+ connectorCatalog: {
+ getConnectorCatalog: async () => [catalogEntry],
+ listConnectors: async () => [],
+ getConnector: async () => created,
+ getToolsByConnectorId: async () => [],
+ createConnector,
+ updateConnector: async () => created,
+ authenticateConnector: async () => ({ authorization_endpoint: '' }),
+ disconnectConnector: async () => created,
+ },
+ }),
+ });
+
+ render(
+ <AnalyticsProvider track={track}>
+ <ServerProvider server={server}>
+ <ConnectorSettings />
+ </ServerProvider>
+ </AnalyticsProvider>,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Connect' }));
+
+ await waitFor(() => {
+ expect(createConnector).toHaveBeenCalledWith({
+ name: catalogEntry.name,
+ description: catalogEntry.description,
+ url: catalogEntry.url,
+ auth: { type: 'none' },
+ });
+ });
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Settings.CONNECTOR_SAVED, {
+ connector_name: catalogEntry.name,
+ mode: 'create',
+ });
+ });
+
+ it('tracks connector deleted after confirm', async () => {
+ const connector: ConnectorBase = {
+ id: 'custom-mcp',
+ name: 'Custom MCP',
+ description: 'Custom tools',
+ url: 'https://mcp.example.com/mcp',
+ authenticated: true,
+ requiresAuth: false,
+ auth: { type: 'none' },
+ };
+ const deleteConnector = vi.fn(async () => {});
+ const track = vi.fn();
+ const server = createMockAgentUIServer({
+ catalog: createMockCatalog({
+ connectorCatalog: {
+ getConnectorCatalog: async () => [],
+ listConnectors: async () => [connector],
+ getConnector: async () => connector,
+ getToolsByConnectorId: async () => [],
+ createConnector: async () => connector,
+ updateConnector: async () => connector,
+ authenticateConnector: async () => ({ authorization_endpoint: '' }),
+ disconnectConnector: async () => connector,
+ deleteConnector,
+ },
+ }),
+ });
+
+ render(
+ <AnalyticsProvider track={track}>
+ <ServerProvider server={server}>
+ <ConnectorSettings />
+ </ServerProvider>
+ </AnalyticsProvider>,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Remove Custom MCP' }));
+ fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: 'Remove' }));
+
+ await waitFor(() => expect(deleteConnector).toHaveBeenCalledWith({ id: connector.id }));
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Settings.CONNECTOR_DELETED, {
+ connector_name: connector.name,
+ });
+ });
+
+ it('tracks connector disconnected without emitting deleted', async () => {
+ const connector: ConnectorBase = {
+ id: 'oauth-mcp',
+ name: 'OAuth MCP',
+ description: 'OAuth tools',
+ url: 'https://mcp.example.com/mcp',
+ authenticated: true,
+ requiresAuth: false,
+ auth: { type: 'dcr' },
+ };
+ const disconnectConnector = vi.fn(async () => ({ ...connector, authenticated: false, requiresAuth: true }));
+ const track = vi.fn();
+ const server = createMockAgentUIServer({
+ catalog: createMockCatalog({
+ connectorCatalog: {
+ getConnectorCatalog: async () => [],
+ listConnectors: async () => [connector],
+ getConnector: async () => connector,
+ getToolsByConnectorId: async () => [],
+ createConnector: async () => connector,
+ updateConnector: async () => connector,
+ authenticateConnector: async () => ({ authorization_endpoint: '' }),
+ disconnectConnector,
+ deleteConnector: async () => {},
+ },
+ }),
+ });
+
+ render(
+ <AnalyticsProvider track={track}>
+ <ServerProvider server={server}>
+ <ConnectorSettings />
+ </ServerProvider>
+ </AnalyticsProvider>,
+ );
+
+ fireEvent.click(await screen.findByText(connector.name));
+ fireEvent.click(await screen.findByRole('button', { name: 'Disconnect' }));
+
+ await waitFor(() => expect(disconnectConnector).toHaveBeenCalledWith({ id: connector.id }));
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Settings.CONNECTOR_DISCONNECTED, {
+ connector_name: connector.name,
+ });
+ expect(track).not.toHaveBeenCalledWith(AnalyticsEvents.Settings.CONNECTOR_DELETED, expect.anything());
+ });
});
diff --git a/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx b/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx
index 47e14a931..a7de68404 100644
--- a/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx
+++ b/packages/trueforge-ui/test/containers/SettingsBuilder/SkillSettings.test.tsx
@@ -3,6 +3,9 @@ import { fireEvent, render, screen, waitFor, within } from '@testing-library/rea
import type { ReactNode } from 'react';
import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
+import type { TrackAnalytics } from '@/analytics/types.js';
import SkillSettings from '@/containers/SettingsBuilder/SkillSettings.js';
import { ServerProvider } from '@/server/ServerContext.js';
import type { CreateSkillRequest, DefinedSkill, SkillCatalogEntry } from '@/server/types.js';
@@ -27,7 +30,7 @@ const catalogEntry: SkillCatalogEntry = {
};
/** In-memory host: catalog is fixed, defined skills live in a mutable list. */
-function createFakeHost(initial: DefinedSkill[] = []) {
+function createFakeHost(initial: DefinedSkill[] = [], track?: TrackAnalytics) {
let defined = [...initial];
const created: CreateSkillRequest[] = [];
@@ -64,13 +67,17 @@ function createFakeHost(initial: DefinedSkill[] = []) {
return {
created,
getDefined: () => defined,
- wrapper: ({ children }: { children: ReactNode }) => <ServerProvider server={server}>{children}</ServerProvider>,
+ wrapper: ({ children }: { children: ReactNode }) => {
+ const tree = <ServerProvider server={server}>{children}</ServerProvider>;
+ return track != null ? <AnalyticsProvider track={track}>{tree}</AnalyticsProvider> : tree;
+ },
};
}
describe('SkillSettings', () => {
it('selects a catalog skill and moves it out of Available', async () => {
- const host = createFakeHost();
+ const track = vi.fn();
+ const host = createFakeHost([], track);
const { wrapper: Wrapper } = host;
render(
@@ -95,6 +102,7 @@ describe('SkillSettings', () => {
ref: catalogEntry.ref,
},
]);
+ expect(track).toHaveBeenCalledWith(AnalyticsEvents.Settings.SKILL_IMPORTED, { skill_name: catalogEntry.name });
});
it('returns a removed registry skill to Available', async () => {
diff --git a/packages/trueforge-ui/test/containers/ThreadListContainer.test.tsx b/packages/trueforge-ui/test/containers/ThreadListContainer.test.tsx
index b777e42d5..f557810c6 100644
--- a/packages/trueforge-ui/test/containers/ThreadListContainer.test.tsx
+++ b/packages/trueforge-ui/test/containers/ThreadListContainer.test.tsx
@@ -9,6 +9,8 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import type { ReactNode } from 'react';
import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { AnalyticsProvider } from '@/analytics/AnalyticsProvider.js';
+import { AnalyticsEvents } from '@/analytics/events.js';
import type { ThreadListRowProps } from '@/atoms/ThreadListRow.js';
import { CompactLayoutProvider } from '@/atoms/lib/CompactLayoutContext.js';
import { ThreadListContainer, type ThreadListContainerProps } from '@/containers/ThreadListContainer.js';
@@ -113,6 +115,7 @@ function renderThreadList({
canRename = false,
permissions,
variant,
+ track,
}: {
adapter: ExternalStoreThreadListAdapter;
onThreadOpen?: () => void;
@@ -122,6 +125,7 @@ function renderThreadList({
listPermissions: (req: { resourceType: string; resourceIds: string[] }) => Promise<ListPermissionsResponse>;
};
variant?: ThreadListContainerProps['variant'];
+ track?: (eventName: string, data?: Record<string, string | number | boolean | undefined>) => void;
}) {
const list = (
<SlotsProvider overrides={{ ThreadListRow: ThreadListRowOverride }}>
@@ -134,9 +138,10 @@ function renderThreadList({
</ToasterProvider>
</SlotsProvider>
);
+ const withAnalytics = track != null ? <AnalyticsProvider track={track}>{list}</AnalyticsProvider> : list;
if (!canDelete && !canRename) {
- return render(list);
+ return render(withAnalytics);
}
return render(
@@ -147,7 +152,7 @@ function renderThreadList({
...(permissions === undefined ? {} : { permissions }),
})}
>
- {list}
+ {withAnalytics}
</ServerProvider>,
);
}
@@ -349,6 +354,7 @@ describe('ThreadListContainer', () => {
it('exposes delete only for remote sessions and delegates deletion to the runtime', async () => {
const onDelete = vi.fn(async () => {});
+ const track = vi.fn();
renderThreadList({
adapter: {
@@ -369,6 +375,7 @@ describe('ThreadListContainer', () => {
onDelete,
},
canDelete: true,
+ track,
});
const actionButtons = screen.getAllByRole('button', { name: 'Session actions' });
@@ -383,6 +390,10 @@ describe('ThreadListContainer', () => {
await waitFor(() => {
expect(onDelete).toHaveBeenCalledWith('thread-1');
});
+ expect(track).toHaveBeenCalledWith(
+ AnalyticsEvents.Session.DELETED,
+ expect.objectContaining({ session_id: 'session-1' }),
+ );
});
it('hides rename when the server does not opt in', () => {
diff --git a/packages/trueforge-ui/test/publicUiExports.test.ts b/packages/trueforge-ui/test/publicUiExports.test.ts
index d8b6f70ec..9cd132649 100644
--- a/packages/trueforge-ui/test/publicUiExports.test.ts
+++ b/packages/trueforge-ui/test/publicUiExports.test.ts
@@ -35,6 +35,8 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'AgentStepsContainer',
'AgentsLibrary',
'AgentsLibraryButton',
+ 'AnalyticsEvents',
+ 'AnalyticsProvider',
'ApprovalNavBanner',
'ApprovalNavContainer',
'AskUserContainer',
@@ -204,6 +206,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'useDraftCatalog',
'useToaster',
'useToasterOptional',
+ 'useTrackAnalytics',
'useMCPAuth',
'useOptionalAgentMetricsServer',
'useOptionalAgentSessionsServer',
@@ -235,6 +238,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'useTrueForgeToolResponses',
'useTrueForgeTurnId',
'useTrueForgeUpdateAgentSpec',
+ 'withSessionProps',
];
describe('public runtime exports', () => {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 220ed491b..6fcba7b20 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -114,6 +114,9 @@ importers:
monaco-editor:
specifier: ^0.57.0
version: 0.57.0
+ posthog-js:
+ specifier: ^1.434.17
+ version: 1.435.2(@types/[email protected])([email protected])
react:
specifier: ^19.2.4
version: 19.3.0
@@ -2388,6 +2391,15 @@ packages:
'@pondwader/[email protected]':
resolution: {integrity: sha512-bQY06wzzR8D2+vVCUoBsr5QS2U6UgPUQRmErNwtsuI6vLcyRKkafjkr3KxbtGFf9aBBIV2mcvlsKD1UYaIV+sg==}
+ '@posthog/[email protected]':
+ resolution: {integrity: sha512-EWoVzs1vVY7ihpn8yOjj3jyjriHUEEMVSBNL/TW3hk09fTriWRe76vJXrRg0G0yjTYxHmtlSkNn4mOV24ZEzzA==}
+
+ '@posthog/[email protected]':
+ resolution: {integrity: sha512-2mYxGbDmTLUs096VbcZqSWo0lrI48/BrX65r54NynxxFq409BOx9w73HxOAtOKZ1vblkdV6/GxQTe7KDcIQidg==}
+
+ '@posthog/[email protected]':
+ resolution: {integrity: sha512-tYAVzNojWckuG/wxBB0fwE70sFruQQq4xbhkci7eH2ARU3mMfUTkvpN1HwBMpm0AtbxidLiH0IFvagmdJ8opPw==}
+
'@protobufjs/[email protected]':
resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
@@ -4557,6 +4569,9 @@ packages:
resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==}
engines: {node: '>=18'}
+ resolution: {integrity: sha512-BRWgOLKkFeCgRudR6zrs8p9XJZcE14grzKMMssoYrk6krtuEZ7MTKPIY5RzOnqsEKIR9kst7wNzphttraT+Yqw==}
+
resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
engines: {node: '>= 0.10'}
@@ -5119,6 +5134,9 @@ packages:
resolution: {integrity: sha512-OP2IUU6HeYKJi3i0z4A19kHMQoLVs4Hc+DPqqxI2h/DPZHTm/vjsfC6P0b4jCMy14XizLBqvndQ+UilD7707Jw==}
+ resolution: {integrity: sha512-zdxgIEddhfsyCaWpJ2SdXEP8ZMrKJ6+5jl4OupODcywU0IhRk6gdXuVGcPICyfx2H97hVK7xmJtRLPjkxAX8Vw==}
+
resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}
engines: {node: '>=16.0.0'}
@@ -6562,6 +6580,25 @@ packages:
resolution: {integrity: sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==}
engines: {node: '>=0.10.0'}
+ resolution: {integrity: sha512-NfmEfNJkXpejZ27/fjVrXLT1reFme6MnRi8o53Hu3kuNWWEe9FeSDY5vsQ1OfCa1mZzXv0qE6OnBlTah64Cp1A==}
+ peerDependencies:
+ '@types/react': '>=16.8.0'
+ react: '>=16.8.0'
+ peerDependenciesMeta:
+ '@types/react':
+ optional: true
+ react:
+ optional: true
+
+ resolution: {integrity: sha512-ej2aVZ+vZ8WO7tvlQWRM9N63A0KzF9q4mWJfDUHgYaIofWY9hu74QdnQrjoPMmZi2/nZ5gN0bJCQF49xQqx09Q==}
+ peerDependencies:
+ preact-render-to-string: '>=5'
+ peerDependenciesMeta:
+ preact-render-to-string:
+ optional: true
+
resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
engines: {node: '>= 0.8.0'}
@@ -6629,6 +6666,9 @@ packages:
resolution: {integrity: sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==}
engines: {node: '>=0.6'}
+ resolution: {integrity: sha512-lT5yCqEBgfoMYpf3F2xQRK7zEr1rhIIZuceDK6+xRkJQ4NMbHTwXqk4NkwDwQMNqXgG9r9fyHnzwNVs6zV5KRw==}
+
resolution: {integrity: sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==}
@@ -7623,6 +7663,12 @@ packages:
resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
+ resolution: {integrity: sha512-rLcLXA2sx6+9dE88NHFubwTtGxpK4yYBLj6qHPdFoCaLr0cXGb4efOqtKLlm4loGA4OEKHIQKMKzZkKyOh5ctw==}
+
+ resolution: {integrity: sha512-oto5x6dLEgrRqfcWed+pZEUb2q6ikbFmqF54CRDhI/QGbn+qxC49b4C4OkbH+kb9C3a8shpFD3SgR9kRcs80ZQ==}
+
resolution: {integrity: sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==}
engines: {node: '>=12'}
@@ -9842,6 +9888,17 @@ snapshots:
'@pondwader/[email protected]': {}
+ '@posthog/[email protected]':
+ dependencies:
+ '@posthog/core': 1.55.2
+ '@posthog/types': 1.413.0
+
+ '@posthog/[email protected]':
+ dependencies:
+ '@posthog/types': 1.413.0
+
+ '@posthog/[email protected]': {}
+
'@protobufjs/[email protected]': {}
'@protobufjs/[email protected]': {}
@@ -12001,6 +12058,8 @@ snapshots:
+
dependencies:
object-assign: 4.1.1
@@ -12754,6 +12813,8 @@ snapshots:
+
dependencies:
flat-cache: 4.0.1
@@ -14584,6 +14645,26 @@ snapshots:
dependencies:
xtend: 4.0.2
+ dependencies:
+ '@posthog/browser-common': 0.9.0
+ '@posthog/core': 1.55.2
+ '@posthog/types': 1.413.0
+ core-js: 3.50.0
+ dompurify: 3.4.15
+ fflate: 0.4.9
+ preact: 10.29.8
+ query-selector-shadow-dom: 1.0.1
+ web-vitals: 6.2.2
+ web-vitals-soft-navs: [email protected]
+ optionalDependencies:
+ '@types/react': 19.3.0
+ react: 19.3.0
+ transitivePeerDependencies:
+ - preact-render-to-string
+
+
@@ -14654,6 +14735,8 @@ snapshots:
es-define-property: 1.0.1
side-channel: 1.1.1
+
@@ -15909,6 +15992,10 @@ snapshots:
+
+
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 2909f600d..4b4031918 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -9,6 +9,7 @@ allowBuilds:
'@parcel/watcher': true
'@swc/core': true
better-sqlite3: false
+ core-js: false
esbuild: true
# Fern-generated SDK tests (packages/trueforge-sdk) run msw's postinstall.
msw: true