diff --git a/.env.example b/.env.example index b39f2a219..f72ea4e29 100644 --- a/.env.example +++ b/.env.example @@ -13,3 +13,8 @@ POSTHOG_PROJECT_ID= # NGAF_TELEMETRY_SAMPLE_RATE=1.0 # DO_NOT_TRACK=1 # cross-vendor opt-out # NGAF_TELEMETRY_DISABLED=1 # package-specific opt-out + +# Cockpit shell analytics (apps/cockpit) +NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN= +NEXT_PUBLIC_COCKPIT_POSTHOG_HOST=https://us.i.posthog.com +NEXT_PUBLIC_COCKPIT_CAPTURE_LOCAL=false diff --git a/apps/cockpit/instrumentation-client.ts b/apps/cockpit/instrumentation-client.ts new file mode 100644 index 000000000..ae24d3687 --- /dev/null +++ b/apps/cockpit/instrumentation-client.ts @@ -0,0 +1,20 @@ +// SPDX-License-Identifier: MIT +import posthog from 'posthog-js'; +import { getCockpitSessionId } from './src/lib/analytics/distinct-id'; +import { shouldCaptureAnalytics } from './src/lib/analytics/properties'; + +const token = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN; +const captureLocal = process.env.NEXT_PUBLIC_COCKPIT_CAPTURE_LOCAL === 'true'; +const host = typeof window === 'undefined' ? undefined : window.location.host; +const doNotTrack = typeof navigator !== 'undefined' && navigator.doNotTrack === '1'; + +if (shouldCaptureAnalytics({ token, captureLocal, host, doNotTrack })) { + posthog.init(token!, { + api_host: process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_HOST ?? 'https://us.i.posthog.com', + persistence: 'memory', + bootstrap: { distinctID: getCockpitSessionId() }, + autocapture: false, + capture_pageview: false, + defaults: '2026-01-30', + }); +} diff --git a/apps/cockpit/package.json b/apps/cockpit/package.json index fd8250ec8..7b15cf322 100644 --- a/apps/cockpit/package.json +++ b/apps/cockpit/package.json @@ -9,6 +9,7 @@ "clsx": "^2.1.1", "marked": "^15.0.0", "next": "~16.1.6", + "posthog-js": "^1.372.6", "react": "^19.0.0", "react-dom": "^19.0.0", "tailwind-merge": "^2.5.0" diff --git a/apps/cockpit/project.json b/apps/cockpit/project.json index 3830f04ea..3fe772018 100644 --- a/apps/cockpit/project.json +++ b/apps/cockpit/project.json @@ -57,7 +57,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-streaming-angular --port 4300", + "npx nx serve cockpit-langgraph-streaming-angular:serve:cockpit --port 4300", "cd cockpit/langgraph/streaming/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -68,7 +68,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-persistence-angular --port 4301", + "npx nx serve cockpit-langgraph-persistence-angular:serve:cockpit --port 4301", "cd cockpit/langgraph/persistence/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -79,7 +79,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-interrupts-angular --port 4302", + "npx nx serve cockpit-langgraph-interrupts-angular:serve:cockpit --port 4302", "cd cockpit/langgraph/interrupts/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -90,7 +90,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-memory-angular --port 4303", + "npx nx serve cockpit-langgraph-memory-angular:serve:cockpit --port 4303", "cd cockpit/langgraph/memory/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -101,7 +101,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-durable-execution-angular --port 4304", + "npx nx serve cockpit-langgraph-durable-execution-angular:serve:cockpit --port 4304", "cd cockpit/langgraph/durable-execution/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -112,7 +112,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-subgraphs-angular --port 4305", + "npx nx serve cockpit-langgraph-subgraphs-angular:serve:cockpit --port 4305", "cd cockpit/langgraph/subgraphs/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -123,7 +123,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-time-travel-angular --port 4306", + "npx nx serve cockpit-langgraph-time-travel-angular:serve:cockpit --port 4306", "cd cockpit/langgraph/time-travel/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -134,7 +134,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-langgraph-deployment-runtime-angular --port 4307", + "npx nx serve cockpit-langgraph-deployment-runtime-angular:serve:cockpit --port 4307", "cd cockpit/langgraph/deployment-runtime/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -145,7 +145,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-deep-agents-planning-angular --port 4310", + "npx nx serve cockpit-deep-agents-planning-angular:serve:cockpit --port 4310", "cd cockpit/deep-agents/planning/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -156,7 +156,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-deep-agents-filesystem-angular --port 4311", + "npx nx serve cockpit-deep-agents-filesystem-angular:serve:cockpit --port 4311", "cd cockpit/deep-agents/filesystem/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -167,7 +167,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-deep-agents-subagents-angular --port 4312", + "npx nx serve cockpit-deep-agents-subagents-angular:serve:cockpit --port 4312", "cd cockpit/deep-agents/subagents/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -178,7 +178,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-deep-agents-memory-angular --port 4313", + "npx nx serve cockpit-deep-agents-memory-angular:serve:cockpit --port 4313", "cd cockpit/deep-agents/memory/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -189,7 +189,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-deep-agents-skills-angular --port 4314", + "npx nx serve cockpit-deep-agents-skills-angular:serve:cockpit --port 4314", "cd cockpit/deep-agents/skills/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true @@ -200,7 +200,7 @@ "options": { "commands": [ "npx nx serve cockpit --port 4201", - "npx nx serve cockpit-deep-agents-sandboxes-angular --port 4315", + "npx nx serve cockpit-deep-agents-sandboxes-angular:serve:cockpit --port 4315", "cd cockpit/deep-agents/sandboxes/python && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123" ], "parallel": true diff --git a/apps/cockpit/scripts/serve-example.ts b/apps/cockpit/scripts/serve-example.ts index cca450f9b..f129c7ba0 100644 --- a/apps/cockpit/scripts/serve-example.ts +++ b/apps/cockpit/scripts/serve-example.ts @@ -30,12 +30,12 @@ process.on('SIGTERM', cleanup); run('cockpit', 'npx nx serve cockpit --port 4201', '36'); if (allMode) { - capabilities.forEach((c) => run(c.id, `npx nx serve ${c.angularProject} --port ${c.port}`, '33')); + capabilities.forEach((c) => run(c.id, `npx nx serve ${c.angularProject}:serve:cockpit --port ${c.port}`, '33')); console.log('\nšŸš€ Starting cockpit + all 14 examples\n'); } else { const cap = findCapability(capabilityArg!); if (!cap) { console.error(`Unknown: ${capabilityArg}`); process.exit(1); } - run(cap.id, `npx nx serve ${cap.angularProject} --port ${cap.port}`, '33'); + run(cap.id, `npx nx serve ${cap.angularProject}:serve:cockpit --port ${cap.port}`, '33'); run(`${cap.id}-py`, `cd ${cap.pythonDir} && source $HOME/.local/bin/env 2>/dev/null; uv sync && uv run langgraph dev --port 8123`, '35'); console.log(`\nšŸš€ ${cap.id}: cockpit=4201 angular=${cap.port} langgraph=8123\n`); } diff --git a/apps/cockpit/src/components/cockpit-shell.tsx b/apps/cockpit/src/components/cockpit-shell.tsx index 273fdd273..9c8e7ff7c 100644 --- a/apps/cockpit/src/components/cockpit-shell.tsx +++ b/apps/cockpit/src/components/cockpit-shell.tsx @@ -102,6 +102,7 @@ export function CockpitShell({ modes={PRIMARY_MODES} activeMode={activeMode} onChange={setActiveMode} + capability={entry.topic} /> @@ -112,6 +113,7 @@ export function CockpitShell({ {activeMode === 'Code' ? ( @@ -121,10 +123,11 @@ export function CockpitShell({ backendAssetPaths={backendAssetPaths} codeFiles={contentBundle.codeFiles} promptFiles={contentBundle.promptFiles} + capability={entry.topic} /> ) : null} {activeMode === 'Docs' ? ( - + ) : null} {activeMode === 'API' ? ( diff --git a/apps/cockpit/src/components/code-mode/code-mode.spec.tsx b/apps/cockpit/src/components/code-mode/code-mode.spec.tsx index 53dc0a0d4..ec661e005 100644 --- a/apps/cockpit/src/components/code-mode/code-mode.spec.tsx +++ b/apps/cockpit/src/components/code-mode/code-mode.spec.tsx @@ -2,7 +2,11 @@ import React from 'react'; import { act } from 'react'; import { createRoot } from 'react-dom/client'; -import { afterEach, describe, expect, it } from 'vitest'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +vi.mock('../../lib/analytics/client', () => ({ track: vi.fn() })); + +import { track } from '../../lib/analytics/client'; import { CodeMode } from './code-mode'; describe('CodeMode', () => { @@ -14,6 +18,7 @@ describe('CodeMode', () => { root?.unmount(); }); container?.remove(); + vi.clearAllMocks(); }); it('renders Shiki-highlighted HTML for the active file', () => { @@ -111,4 +116,42 @@ describe('CodeMode', () => { expect(container.textContent).toContain('You are a helpful assistant.'); }); + + it('fires cockpit:code_copied when the Copy button is clicked', () => { + container = document.createElement('div'); + document.body.appendChild(container); + root = createRoot(container); + + Object.assign(navigator, { + clipboard: { writeText: vi.fn(() => Promise.resolve()) }, + }); + + act(() => { + root!.render( + const x = 1;' }} + promptFiles={{}} + capability="streaming" + />, + ); + }); + + const copyBtn = container.querySelector( + 'button[aria-label^="Copy"]', + ) as HTMLButtonElement | null; + expect(copyBtn).not.toBeNull(); + + act(() => { + copyBtn!.click(); + }); + + expect(track).toHaveBeenCalledWith('cockpit:code_copied', { + capability: 'streaming', + surface: 'code_mode', + file_path: 'src/app.tsx', + }); + }); }); diff --git a/apps/cockpit/src/components/code-mode/code-mode.tsx b/apps/cockpit/src/components/code-mode/code-mode.tsx index 23b07118c..37a1a0e82 100644 --- a/apps/cockpit/src/components/code-mode/code-mode.tsx +++ b/apps/cockpit/src/components/code-mode/code-mode.tsx @@ -2,6 +2,7 @@ import React from 'react'; import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'; +import { track } from '../../lib/analytics/client'; interface CodeModeProps { entryTitle: string; @@ -9,11 +10,20 @@ interface CodeModeProps { backendAssetPaths: readonly string[]; codeFiles: Record; promptFiles: Record; + capability?: string; } const getTabLabel = (path: string): string => path.split('/').pop() ?? path; -function CodeFileContent({ path, content }: { path: string; content: string | undefined }) { +function CodeFileContent({ + path, + content, + capability, +}: { + path: string; + content: string | undefined; + capability?: string; +}) { if (!content) { return

No source available for {getTabLabel(path)}

; } @@ -38,6 +48,11 @@ function CodeFileContent({ path, content }: { path: string; content: string | un 
const x = 1;
', + ); + const btn = container!.querySelector('[data-copy-code]') as HTMLElement; + act(() => { + btn.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })); + }); + expect(track).toHaveBeenCalledWith('cockpit:code_copied', { + capability: 'streaming', + surface: 'docs_code_snippet', + }); + }); + + it('fires cockpit:code_copied with surface=agentic_prompt on prompt copy click', () => { + renderWith( + '
You are helpful.
', + ); + const btn = container!.querySelector('[data-copy-prompt]') as HTMLElement; + act(() => { + btn.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })); + }); + expect(track).toHaveBeenCalledWith('cockpit:code_copied', { + capability: 'streaming', + surface: 'agentic_prompt', + }); + }); + }); }); diff --git a/apps/cockpit/src/components/narrative-docs/narrative-docs.tsx b/apps/cockpit/src/components/narrative-docs/narrative-docs.tsx index d6f8ce8d7..012c1a690 100644 --- a/apps/cockpit/src/components/narrative-docs/narrative-docs.tsx +++ b/apps/cockpit/src/components/narrative-docs/narrative-docs.tsx @@ -1,6 +1,7 @@ 'use client'; import React, { useCallback } from 'react'; +import { track } from '../../lib/analytics/client'; interface NarrativeDoc { title: string; @@ -10,9 +11,10 @@ interface NarrativeDoc { interface NarrativeDocsProps { narrativeDocs: NarrativeDoc[]; + capability?: string; } -export function NarrativeDocs({ narrativeDocs }: NarrativeDocsProps) { +export function NarrativeDocs({ narrativeDocs, capability }: NarrativeDocsProps) { const handleClick = useCallback((e: React.MouseEvent) => { const target = e.target as HTMLElement; @@ -21,6 +23,7 @@ export function NarrativeDocs({ narrativeDocs }: NarrativeDocsProps) { const codeBlock = copyCodeBtn.closest('.doc-codeblock'); const code = codeBlock?.querySelector('pre code')?.textContent ?? ''; navigator.clipboard.writeText(code); + track('cockpit:code_copied', { capability, surface: 'docs_code_snippet' }); copyCodeBtn.textContent = 'Copied!'; setTimeout(() => { copyCodeBtn.textContent = 'Copy'; }, 1500); return; @@ -31,11 +34,12 @@ export function NarrativeDocs({ narrativeDocs }: NarrativeDocsProps) { const promptBlock = copyPromptBtn.closest('.doc-prompt'); const text = promptBlock?.querySelector('.doc-prompt__content')?.textContent ?? ''; navigator.clipboard.writeText(text); + track('cockpit:code_copied', { capability, surface: 'agentic_prompt' }); copyPromptBtn.textContent = 'Copied!'; setTimeout(() => { copyPromptBtn.textContent = 'Copy prompt'; }, 1500); return; } - }, []); + }, [capability]); if (narrativeDocs.length === 0) { return ( diff --git a/apps/cockpit/src/components/run-mode/run-mode.spec.tsx b/apps/cockpit/src/components/run-mode/run-mode.spec.tsx index 4189a4cb7..2e574f1ba 100644 --- a/apps/cockpit/src/components/run-mode/run-mode.spec.tsx +++ b/apps/cockpit/src/components/run-mode/run-mode.spec.tsx @@ -1,23 +1,59 @@ +// SPDX-License-Identifier: MIT +/** @vitest-environment jsdom */ import React from 'react'; +import { act } from 'react'; +import { createRoot } from 'react-dom/client'; import { renderToStaticMarkup } from 'react-dom/server'; -import { describe, expect, it } from 'vitest'; +import { afterEach, describe, expect, it, vi } from 'vitest'; + +vi.mock('../../lib/analytics/distinct-id', () => ({ + getCockpitSessionId: () => 'cockpit_test-uuid', +})); + import { RunMode } from './run-mode'; describe('RunMode', () => { + let container: HTMLDivElement | undefined; + let root: ReturnType | undefined; + + afterEach(() => { + act(() => { + root?.unmount(); + }); + container?.remove(); + }); + it('renders an iframe when runtimeUrl is provided', () => { const html = renderToStaticMarkup( - + , ); expect(html).toContain(' { const html = renderToStaticMarkup( - + , ); expect(html).not.toContain(' { + container = document.createElement('div'); + document.body.appendChild(container); + root = createRoot(container); + + act(() => { + root!.render( + , + ); + }); + + const iframe = container.querySelector('iframe') as HTMLIFrameElement; + expect(iframe).not.toBeNull(); + const src = new URL(iframe.src); + expect(src.searchParams.get('cockpit_did')).toBe('cockpit_test-uuid'); + expect(src.searchParams.get('cockpit_cap')).toBe('streaming'); + }); }); diff --git a/apps/cockpit/src/components/run-mode/run-mode.tsx b/apps/cockpit/src/components/run-mode/run-mode.tsx index 1f8772ac2..1cebfac8d 100644 --- a/apps/cockpit/src/components/run-mode/run-mode.tsx +++ b/apps/cockpit/src/components/run-mode/run-mode.tsx @@ -1,12 +1,26 @@ +// SPDX-License-Identifier: MIT import React from 'react'; import { ThemedFrame } from '@ngaf/ui-react'; +import { getCockpitSessionId } from '../../lib/analytics/distinct-id'; interface RunModeProps { entryTitle: string; runtimeUrl: string | null; + capabilitySlug: string; } -export function RunMode({ entryTitle, runtimeUrl }: RunModeProps) { +function buildIframeSrc(runtimeUrl: string, capabilitySlug: string): string { + const url = new URL(runtimeUrl); + url.searchParams.set('cockpit_did', getCockpitSessionId()); + url.searchParams.set('cockpit_cap', capabilitySlug); + const phk = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN; + if (phk) url.searchParams.set('cockpit_phk', phk); + const host = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_HOST; + if (host) url.searchParams.set('cockpit_host', host); + return url.toString(); +} + +export function RunMode({ entryTitle, runtimeUrl, capabilitySlug }: RunModeProps) { if (!runtimeUrl) { return (
@@ -18,7 +32,7 @@ export function RunMode({ entryTitle, runtimeUrl }: RunModeProps) { return (
({ track: vi.fn() })); + +import { track } from '../../lib/analytics/client'; +import { NavigationGroups } from './navigation-groups'; +import { buildNavigationTree } from '../../lib/route-resolution'; +import { cockpitManifest } from '@ngaf/cockpit-registry'; + +describe('NavigationGroups capability link instrumentation', () => { + let container: HTMLDivElement | undefined; + let root: ReturnType | undefined; + + afterEach(() => { + act(() => { + root?.unmount(); + }); + container?.remove(); + vi.clearAllMocks(); + }); + + it('fires cockpit:recipe_opened on capability link click', () => { + container = document.createElement('div'); + document.body.append(container); + root = createRoot(container); + + const currentEntry = cockpitManifest.find( + (candidate) => + candidate.product === 'langgraph' && + candidate.section === 'core-capabilities' && + candidate.topic === 'streaming' && + candidate.language === 'python', + )!; + + act(() => { + root!.render( + , + ); + }); + + const links = Array.from( + container.querySelectorAll('a[data-capability-link]'), + ); + expect(links.length).toBeGreaterThan(0); + + // Find a link with a different capability (not the current one). + const otherLink = links.find((l) => l.getAttribute('aria-current') !== 'page'); + expect(otherLink).toBeDefined(); + + act(() => { + otherLink!.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })); + }); + + expect(track).toHaveBeenCalledWith( + 'cockpit:recipe_opened', + expect.objectContaining({ + capability: expect.any(String), + category: expect.any(String), + from_capability: 'streaming', + }), + ); + }); +}); diff --git a/apps/cockpit/src/components/sidebar/navigation-groups.tsx b/apps/cockpit/src/components/sidebar/navigation-groups.tsx index a55818dcd..6331eb5ab 100644 --- a/apps/cockpit/src/components/sidebar/navigation-groups.tsx +++ b/apps/cockpit/src/components/sidebar/navigation-groups.tsx @@ -5,6 +5,7 @@ import type { CockpitManifestEntry } from '@ngaf/cockpit-registry'; import type { NavigationProduct } from '../../lib/route-resolution'; import { toCockpitPath } from '../../lib/route-resolution'; import { PRODUCT_LABELS, stripProductPrefix } from '../../lib/navigation-labels'; +import { track } from '../../lib/analytics/client'; interface NavigationGroupsProps { tree: NavigationProduct[]; @@ -75,6 +76,14 @@ function ProductGroup({ { + track('cockpit:recipe_opened', { + capability: entry.topic, + category: entry.product, + from_capability: currentEntry.topic, + }); + }} aria-current={isActive ? 'page' : undefined} className={isActive ? 'border-l-2 border-[var(--ds-accent)]' : 'border-l-2 border-transparent'} style={{ diff --git a/apps/cockpit/src/lib/analytics/client.spec.ts b/apps/cockpit/src/lib/analytics/client.spec.ts new file mode 100644 index 000000000..00024759a --- /dev/null +++ b/apps/cockpit/src/lib/analytics/client.spec.ts @@ -0,0 +1,37 @@ +// SPDX-License-Identifier: MIT +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { track } from './client'; + +const mocks = vi.hoisted(() => ({ capture: vi.fn(), __loaded: true })); + +vi.mock('posthog-js', () => ({ + default: { + capture: mocks.capture, + get __loaded() { + return mocks.__loaded; + }, + }, +})); + +describe('track', () => { + beforeEach(() => { + mocks.capture.mockClear(); + mocks.__loaded = true; + }); + + test('fires posthog.capture when loaded', () => { + track('cockpit:recipe_opened', { capability: 'streaming' }); + expect(mocks.capture).toHaveBeenCalledWith('cockpit:recipe_opened', { capability: 'streaming' }); + }); + + test('no-ops when posthog not loaded', () => { + mocks.__loaded = false; + track('cockpit:mode_switched', { capability: 'x', from_mode: 'run', to_mode: 'code' }); + expect(mocks.capture).not.toHaveBeenCalled(); + }); + + test('passes empty properties when not provided', () => { + track('cockpit:code_copied'); + expect(mocks.capture).toHaveBeenCalledWith('cockpit:code_copied', {}); + }); +}); diff --git a/apps/cockpit/src/lib/analytics/client.ts b/apps/cockpit/src/lib/analytics/client.ts new file mode 100644 index 000000000..af4176f96 --- /dev/null +++ b/apps/cockpit/src/lib/analytics/client.ts @@ -0,0 +1,13 @@ +// SPDX-License-Identifier: MIT +import posthog from 'posthog-js'; +import type { CockpitShellEvent, CockpitShellProps } from './events'; + +export function track(event: CockpitShellEvent, props: CockpitShellProps = {}): void { + try { + if (typeof window !== 'undefined' && (posthog as unknown as { __loaded?: boolean }).__loaded) { + posthog.capture(event, props); + } + } catch { + // silent fail + } +} diff --git a/apps/cockpit/src/lib/analytics/distinct-id.spec.ts b/apps/cockpit/src/lib/analytics/distinct-id.spec.ts new file mode 100644 index 000000000..55cf2c5f1 --- /dev/null +++ b/apps/cockpit/src/lib/analytics/distinct-id.spec.ts @@ -0,0 +1,15 @@ +// SPDX-License-Identifier: MIT +import { describe, test, expect, beforeEach } from 'vitest'; +import { getCockpitSessionId, _resetCockpitSessionIdForTesting } from './distinct-id'; + +describe('getCockpitSessionId', () => { + beforeEach(() => _resetCockpitSessionIdForTesting()); + + test('returns stable id within process', () => { + expect(getCockpitSessionId()).toBe(getCockpitSessionId()); + }); + + test('id has cockpit_ prefix + uuid shape', () => { + expect(getCockpitSessionId()).toMatch(/^cockpit_[0-9a-f-]{36}$/); + }); +}); diff --git a/apps/cockpit/src/lib/analytics/distinct-id.ts b/apps/cockpit/src/lib/analytics/distinct-id.ts new file mode 100644 index 000000000..70516e477 --- /dev/null +++ b/apps/cockpit/src/lib/analytics/distinct-id.ts @@ -0,0 +1,12 @@ +// SPDX-License-Identifier: MIT +let cached: string | null = null; + +export function getCockpitSessionId(): string { + if (!cached) cached = `cockpit_${crypto.randomUUID()}`; + return cached; +} + +// @internal ā€” for tests only +export function _resetCockpitSessionIdForTesting(): void { + cached = null; +} diff --git a/apps/cockpit/src/lib/analytics/events.ts b/apps/cockpit/src/lib/analytics/events.ts new file mode 100644 index 000000000..66f72d573 --- /dev/null +++ b/apps/cockpit/src/lib/analytics/events.ts @@ -0,0 +1,15 @@ +// SPDX-License-Identifier: MIT +export type CockpitShellEvent = + | 'cockpit:recipe_opened' + | 'cockpit:mode_switched' + | 'cockpit:code_copied'; + +export interface CockpitShellProps { + capability?: string; + category?: string; + from_capability?: string; + from_mode?: 'run' | 'code' | 'docs' | 'api'; + to_mode?: 'run' | 'code' | 'docs' | 'api'; + surface?: 'code_mode' | 'docs_code_snippet' | 'agentic_prompt'; + file_path?: string; +} diff --git a/apps/cockpit/src/lib/analytics/properties.spec.ts b/apps/cockpit/src/lib/analytics/properties.spec.ts new file mode 100644 index 000000000..48cd2e8d7 --- /dev/null +++ b/apps/cockpit/src/lib/analytics/properties.spec.ts @@ -0,0 +1,60 @@ +// SPDX-License-Identifier: MIT +import { describe, test, expect } from 'vitest'; +import { shouldCaptureAnalytics } from './properties'; + +describe('shouldCaptureAnalytics', () => { + test('returns false when no token', () => { + expect( + shouldCaptureAnalytics({ + token: undefined, + captureLocal: true, + host: 'cockpit.example.com', + doNotTrack: false, + }), + ).toBe(false); + }); + + test('returns false when DO_NOT_TRACK', () => { + expect( + shouldCaptureAnalytics({ + token: 'phc_x', + captureLocal: true, + host: 'cockpit.example.com', + doNotTrack: true, + }), + ).toBe(false); + }); + + test('returns false on localhost when captureLocal is false', () => { + expect( + shouldCaptureAnalytics({ + token: 'phc_x', + captureLocal: false, + host: 'localhost:4201', + doNotTrack: false, + }), + ).toBe(false); + }); + + test('returns true on localhost when captureLocal is true', () => { + expect( + shouldCaptureAnalytics({ + token: 'phc_x', + captureLocal: true, + host: 'localhost:4201', + doNotTrack: false, + }), + ).toBe(true); + }); + + test('returns true on production host', () => { + expect( + shouldCaptureAnalytics({ + token: 'phc_x', + captureLocal: false, + host: 'cockpit.example.com', + doNotTrack: false, + }), + ).toBe(true); + }); +}); diff --git a/apps/cockpit/src/lib/analytics/properties.ts b/apps/cockpit/src/lib/analytics/properties.ts new file mode 100644 index 000000000..275682814 --- /dev/null +++ b/apps/cockpit/src/lib/analytics/properties.ts @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT +export interface CaptureGuardInput { + token: string | undefined; + captureLocal: boolean; + host: string | undefined; + doNotTrack: boolean; +} + +export function shouldCaptureAnalytics(input: CaptureGuardInput): boolean { + if (!input.token) return false; + if (input.doNotTrack) return false; + if (!input.captureLocal && isLocalhost(input.host)) return false; + return true; +} + +export function isLocalhost(host: string | undefined): boolean { + if (!host) return false; + return ( + host === 'localhost' || + host.startsWith('localhost:') || + host.startsWith('127.0.0.1') || + host.startsWith('0.0.0.0') + ); +} diff --git a/apps/cockpit/test-setup.ts b/apps/cockpit/test-setup.ts index d3ec8158f..ef231d7c9 100644 --- a/apps/cockpit/test-setup.ts +++ b/apps/cockpit/test-setup.ts @@ -1,5 +1,16 @@ import { vi } from 'vitest'; +// jsdom doesn't implement CSS.escape; polyfill it for components that use +// CSS.escape() in event handlers (e.g. code-mode copy button). +if (typeof globalThis.CSS === 'undefined') { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + (globalThis as any).CSS = {}; +} +if (typeof globalThis.CSS.escape !== 'function') { + globalThis.CSS.escape = (value: string): string => + String(value).replace(/[^a-zA-Z0-9_-]/g, (ch) => `\\${ch}`); +} + // next/navigation's useRouter throws "invariant expected app router to be // mounted" when rendered outside an AppRouterContext (e.g. via // renderToStaticMarkup). Provide a no-op mock so components that call diff --git a/apps/website/content/docs/agent/api/api-docs.json b/apps/website/content/docs/agent/api/api-docs.json index cb1309e9f..d84a6f3fe 100644 --- a/apps/website/content/docs/agent/api/api-docs.json +++ b/apps/website/content/docs/agent/api/api-docs.json @@ -1,4 +1,34 @@ [ + { + "name": "AgentLifecycleRegistry", + "kind": "class", + "description": "Optional registry that collects per-instance agent lifecycles within\nan Angular injection context. External instrumentation packages\n(e.g. cockpit-telemetry) provide this token and read from it.\n\n`@ngaf/langgraph` does NOT provide this itself ā€” `agent()` writes to\nthe registry only when an external consumer has provided it.", + "params": [], + "examples": [], + "properties": [ + { + "name": "lifecycles", + "type": "Signal", + "description": "Reactive list of registered lifecycles.", + "optional": false + } + ], + "methods": [ + { + "name": "register", + "signature": "register(lifecycle: AgentLifecycle)", + "description": "", + "params": [ + { + "name": "lifecycle", + "type": "AgentLifecycle", + "description": "", + "optional": false + } + ] + } + ] + }, { "name": "FetchStreamTransport", "kind": "class", @@ -557,6 +587,62 @@ ], "examples": [] }, + { + "name": "AgentLifecycle", + "kind": "interface", + "description": "", + "properties": [ + { + "name": "interruptReceivedAt", + "type": "Signal", + "description": "Epoch ms of the first interrupt$ non-null in this stream. Resets on clearThread.", + "optional": false + }, + { + "name": "interruptResolvedAt", + "type": "Signal", + "description": "Epoch ms of the most recent submit({ interrupt }) call. Resets on clearThread.", + "optional": false + }, + { + "name": "streamErrorAt", + "type": "Signal", + "description": "Epoch ms + classification of the most recent stream error. Resets on clearThread.", + "optional": false + }, + { + "name": "streamStartedAt", + "type": "Signal", + "description": "Epoch ms of the first stream chunk arrival. Resets on clearThread.", + "optional": false + }, + { + "name": "threadCreatedAt", + "type": "Signal", + "description": "Epoch ms when the agent's \"create new thread\" branch fired. Resets on clearThread.", + "optional": false + }, + { + "name": "threadPersistedAt", + "type": "Signal", + "description": "Epoch ms when an existing thread was restored from server (proves persistence). Resets on clearThread.", + "optional": false + }, + { + "name": "toolCallCompletedAt", + "type": "Signal", + "description": "Epoch ms of the first tool call result transition. Resets on clearThread.", + "optional": false + }, + { + "name": "toolCallStartedAt", + "type": "Signal", + "description": "Epoch ms of the first tool call append. Resets on clearThread.", + "optional": false + } + ], + "examples": [] + }, { "name": "AgentOptions", "kind": "interface", @@ -928,6 +1014,12 @@ "description": "Raw LangGraph tool calls (with run-state). Use `toolCalls` for chat rendering.", "optional": false }, + { + "name": "lifecycle", + "type": "AgentLifecycle", + "description": "Lifecycle signals for observability/telemetry. Eight read-only signals\ncapture key transitions (first stream chunk, first interrupt, tool\ncall start/complete, thread create/persist, errors). All reset on\n`switchThread()`. See AgentLifecycle.", + "optional": false + }, { "name": "messageCheckpoints", "type": "Signal>", @@ -1298,6 +1390,12 @@ "description": "Raw LangGraph tool calls (with run-state). Use `toolCalls` for chat rendering.", "optional": false }, + { + "name": "lifecycle", + "type": "AgentLifecycle", + "description": "Lifecycle signals for observability/telemetry. Eight read-only signals\ncapture key transitions (first stream chunk, first interrupt, tool\ncall start/complete, thread create/persist, errors). All reset on\n`switchThread()`. See AgentLifecycle.", + "optional": false + }, { "name": "messageCheckpoints", "type": "Signal>", diff --git a/apps/website/content/docs/agent/getting-started/introduction.mdx b/apps/website/content/docs/agent/getting-started/introduction.mdx index 9eb8b0560..56d43dd28 100644 --- a/apps/website/content/docs/agent/getting-started/introduction.mdx +++ b/apps/website/content/docs/agent/getting-started/introduction.mdx @@ -322,6 +322,9 @@ Your Angular app is a stateless client. All agent state ā€” threads, checkpoints Deterministic testing with MockAgentTransport + + Subscribe to per-agent lifecycle signals via AGENT_LIFECYCLE + Deep dive into how Signals power agent diff --git a/apps/website/content/docs/agent/guides/lifecycle.mdx b/apps/website/content/docs/agent/guides/lifecycle.mdx new file mode 100644 index 000000000..ee29d61d8 --- /dev/null +++ b/apps/website/content/docs/agent/guides/lifecycle.mdx @@ -0,0 +1,79 @@ +# Agent Lifecycle Signals + +The `@ngaf/langgraph` library exposes per-agent lifecycle signals via the `AGENT_LIFECYCLE` injection token. These are timestamps and classifications derived from the existing stream ā€” useful for debugging, custom dashboards, or telemetry integrations. + +## Interface + +```typescript +import { InjectionToken, Signal } from '@angular/core'; + +export interface AgentLifecycle { + /** Epoch ms of the first stream chunk arrival. Resets on clearThread. */ + readonly streamStartedAt: Signal; + /** Epoch ms + classification of the most recent stream error. Resets on clearThread. */ + readonly streamErrorAt: Signal<{ at: number; classification: string } | null>; + /** Epoch ms of the first interrupt$ non-null in this stream. Resets on clearThread. */ + readonly interruptReceivedAt: Signal; + /** Epoch ms of the most recent submit({ interrupt }) call. Resets on clearThread. */ + readonly interruptResolvedAt: Signal; + /** Epoch ms when the agent's "create new thread" branch fired. Resets on clearThread. */ + readonly threadCreatedAt: Signal; + /** Epoch ms when an existing thread was restored from server (proves persistence). Resets on clearThread. */ + readonly threadPersistedAt: Signal; + /** Epoch ms of the first tool call append. Resets on clearThread. */ + readonly toolCallStartedAt: Signal; + /** Epoch ms of the first tool call result transition. Resets on clearThread. */ + readonly toolCallCompletedAt: Signal; +} + +export const AGENT_LIFECYCLE = new InjectionToken('AGENT_LIFECYCLE'); +``` + +## Derivation + +Five of the eight signals derive directly from existing stream subjects on the agent (`status$`, `error$`, `interrupt$`, `toolCalls$`, `history$`): + +| Signal | Source | +|--------|--------| +| `streamStartedAt` | first `status$` transition into a running state | +| `streamErrorAt` | `error$` emission, classified | +| `interruptReceivedAt` | first non-null `interrupt$` value | +| `toolCallStartedAt` | first tool-call append in `toolCalls$` | +| `toolCallCompletedAt` | first tool-call `result` transition in `toolCalls$` | + +Three signals require explicit hook points that the agent already invokes: + +| Signal | Hook | +|--------|------| +| `interruptResolvedAt` | `submit({ interrupt })` | +| `threadCreatedAt` | the agent's "create new thread" branch | +| `threadPersistedAt` | restore-from-server path | + +## Subscribing + +```typescript +import { Component, inject, effect } from '@angular/core'; +import { AGENT_LIFECYCLE } from '@ngaf/langgraph'; + +@Component({ /* ... */ }) +export class MyComponent { + private lifecycle = inject(AGENT_LIFECYCLE); + + constructor() { + effect(() => { + const err = this.lifecycle.streamErrorAt(); + if (err) { + console.log('Stream error at', err.at, 'classification:', err.classification); + } + }); + } +} +``` + +## Reset semantics + +All eight signals reset on `switchThread()` (and on `clearThread()`). This keeps lifecycle observations scoped to the current thread. + +## Privacy + +These signals contain no message content, no model output, no PII. They are timestamps, counts, and short classification strings only. The trust contract at [libs/telemetry/README.md](https://github.com/cacheplane/angular-agent-framework/blob/main/libs/telemetry/README.md) applies: **no app telemetry by default.** Subscribing to `AGENT_LIFECYCLE` in your code does not fire any telemetry; what you do with the signal values is your choice. diff --git a/apps/website/content/docs/chat/api/api-docs.json b/apps/website/content/docs/chat/api/api-docs.json index b64ecfc85..38d561d9f 100644 --- a/apps/website/content/docs/chat/api/api-docs.json +++ b/apps/website/content/docs/chat/api/api-docs.json @@ -1747,6 +1747,12 @@ "description": "", "params": [] }, + { + "name": "clearThread", + "signature": "clearThread()", + "description": "Clears local view state (classifiers, surface store, lifecycle counters)\nfor a new thread.\n\nResets messageCount to 0 and inputSubmittedAt to null. componentReady and\nfirstMessageSent are NOT reset (sticky for the chat instance lifetime).", + "params": [] + }, { "name": "isGenuiTurn", "signature": "isGenuiTurn(message: unknown, _prevMsg: unknown, index: number)", @@ -1942,6 +1948,19 @@ "optional": false } ] + }, + { + "name": "submitMessage", + "signature": "submitMessage(text: string)", + "description": "Programmatic submit. Calls `agent.submit({ message: text })` and updates\nthe CHAT_LIFECYCLE signals. Trimmed-empty text is a no-op.", + "params": [ + { + "name": "text", + "type": "string", + "description": "", + "optional": false + } + ] } ] }, @@ -5961,6 +5980,38 @@ ], "examples": [] }, + { + "name": "ChatLifecycle", + "kind": "interface", + "description": "", + "properties": [ + { + "name": "componentReady", + "type": "Signal", + "description": "True after `` initializes with a non-null agent binding.", + "optional": false + }, + { + "name": "firstMessageSent", + "type": "Signal", + "description": "True after the first user submit. Sticky for the life of the chat instance ā€” does NOT reset on clearThread.", + "optional": false + }, + { + "name": "inputSubmittedAt", + "type": "Signal", + "description": "Epoch ms of the most recent user submit. Resets on clearThread.", + "optional": false + }, + { + "name": "messageCount", + "type": "Signal", + "description": "Count of user submits. Resets on clearThread.", + "optional": false + } + ], + "examples": [] + }, { "name": "ChatRenderEvent", "kind": "interface", diff --git a/apps/website/content/docs/chat/getting-started/introduction.mdx b/apps/website/content/docs/chat/getting-started/introduction.mdx index a888731db..43f5a197d 100644 --- a/apps/website/content/docs/chat/getting-started/introduction.mdx +++ b/apps/website/content/docs/chat/getting-started/introduction.mdx @@ -109,4 +109,11 @@ LangGraph Platform > Customize colors, fonts, and spacing with CSS custom properties. + + Subscribe to per-instance lifecycle signals via `CHAT_LIFECYCLE`. + diff --git a/apps/website/content/docs/chat/guides/lifecycle.mdx b/apps/website/content/docs/chat/guides/lifecycle.mdx new file mode 100644 index 000000000..ea846f208 --- /dev/null +++ b/apps/website/content/docs/chat/guides/lifecycle.mdx @@ -0,0 +1,55 @@ +# Chat Lifecycle Signals + +The `@ngaf/chat` library exposes per-instance lifecycle signals via the `CHAT_LIFECYCLE` injection token. Consumers can subscribe to these signals for debugging, custom dashboards, or telemetry integrations. + +## Interface + +```typescript +import { InjectionToken, Signal } from '@angular/core'; + +export interface ChatLifecycle { + /** True after initializes with a non-null agent binding. */ + readonly componentReady: Signal; + /** True after the first user submit. Sticky for the life of the chat instance ā€” does NOT reset on clearThread. */ + readonly firstMessageSent: Signal; + /** Count of user submits. Resets on clearThread. */ + readonly messageCount: Signal; + /** Epoch ms of the most recent user submit. Resets on clearThread. */ + readonly inputSubmittedAt: Signal; +} + +export const CHAT_LIFECYCLE = new InjectionToken('CHAT_LIFECYCLE'); +``` + +## Subscribing + +```typescript +import { Component, inject, effect } from '@angular/core'; +import { CHAT_LIFECYCLE } from '@ngaf/chat'; + +@Component({ /* ... */ }) +export class MyComponent { + private lifecycle = inject(CHAT_LIFECYCLE); + + constructor() { + effect(() => { + if (this.lifecycle.firstMessageSent()) { + console.log('User sent their first message at', this.lifecycle.inputSubmittedAt()); + } + }); + } +} +``` + +## Reset semantics + +| Signal | Resets on `clearThread()`? | +|--------|----------------------------| +| `componentReady` | no | +| `firstMessageSent` | **no (sticky for life of ``)** | +| `messageCount` | yes (to 0) | +| `inputSubmittedAt` | yes (to null) | + +## Privacy + +These signals contain no message content, no user input, no PII. They are timestamps and counts only. The trust contract at [libs/telemetry/README.md](https://github.com/cacheplane/angular-agent-framework/blob/main/libs/telemetry/README.md) applies: **no app telemetry by default.** Subscribing to `CHAT_LIFECYCLE` in your code does not fire any telemetry; what you do with the signal values is your choice. diff --git a/apps/website/content/docs/render/api/api-docs.json b/apps/website/content/docs/render/api/api-docs.json index 8b5e05fc6..9c0773165 100644 --- a/apps/website/content/docs/render/api/api-docs.json +++ b/apps/website/content/docs/render/api/api-docs.json @@ -348,6 +348,44 @@ ], "examples": [] }, + { + "name": "RenderLifecycle", + "kind": "interface", + "description": "", + "properties": [ + { + "name": "firstMountAt", + "type": "Signal", + "description": "First mount event in this render context. Sticky ā€” does not reset.", + "optional": false + }, + { + "name": "lastHandlerInvokedAt", + "type": "Signal", + "description": "Most recent handler invocation.", + "optional": false + }, + { + "name": "lastMountAt", + "type": "Signal", + "description": "Epoch ms of the most recent mount event.", + "optional": false + }, + { + "name": "lastStateChangeAt", + "type": "Signal", + "description": "Epoch ms of the most recent state-change event.", + "optional": false + }, + { + "name": "mountCount", + "type": "Signal", + "description": "Total mount count since render context started.", + "optional": false + } + ], + "examples": [] + }, { "name": "RenderLifecycleEvent", "kind": "interface", diff --git a/apps/website/content/docs/render/getting-started/introduction.mdx b/apps/website/content/docs/render/getting-started/introduction.mdx index 545f9513a..c4a3b6617 100644 --- a/apps/website/content/docs/render/getting-started/introduction.mdx +++ b/apps/website/content/docs/render/getting-started/introduction.mdx @@ -107,4 +107,7 @@ The rendering pipeline works as follows: Full RenderSpecComponent API reference + + Subscribe to per-context lifecycle signals via RENDER_LIFECYCLE + diff --git a/apps/website/content/docs/render/guides/lifecycle.mdx b/apps/website/content/docs/render/guides/lifecycle.mdx new file mode 100644 index 000000000..c442c9238 --- /dev/null +++ b/apps/website/content/docs/render/guides/lifecycle.mdx @@ -0,0 +1,65 @@ +# Render Lifecycle Signals + +The `@ngaf/render` library exposes per-context lifecycle signals via the `RENDER_LIFECYCLE` injection token. All five signals derive from the existing `RenderEvent` stream via `RenderLifecycleService.notify*` methods ā€” no separate event source, no double-counting. + +## Interface + +```typescript +import { InjectionToken, Signal } from '@angular/core'; + +export interface RenderLifecycle { + /** First mount event in this render context. Sticky ā€” does not reset. */ + readonly firstMountAt: Signal<{ kind: 'spec' | 'element'; elementType?: string; at: number } | null>; + /** Total mount count since render context started. */ + readonly mountCount: Signal; + /** Epoch ms of the most recent mount event. */ + readonly lastMountAt: Signal; + /** Epoch ms of the most recent state-change event. */ + readonly lastStateChangeAt: Signal; + /** Most recent handler invocation. */ + readonly lastHandlerInvokedAt: Signal<{ action: string; at: number } | null>; +} + +export const RENDER_LIFECYCLE = new InjectionToken('RENDER_LIFECYCLE'); +``` + +## Derivation + +All signals derive from `RenderEvent` (see [Events](/docs/render/guides/events)) ā€” `RenderLifecycleService` subscribes to the stream emitted by `RenderSpecComponent` and updates the signals: + +| Signal | Source event | +|--------|--------------| +| `firstMountAt` | first `RenderLifecycleEvent` with `event === 'mounted'` | +| `mountCount` | every `RenderLifecycleEvent` with `event === 'mounted'` | +| `lastMountAt` | every `RenderLifecycleEvent` with `event === 'mounted'` | +| `lastStateChangeAt` | every `RenderStateChangeEvent` | +| `lastHandlerInvokedAt` | every `RenderHandlerEvent` | + +## Subscribing + +```typescript +import { Component, inject, effect } from '@angular/core'; +import { RENDER_LIFECYCLE } from '@ngaf/render'; + +@Component({ /* ... */ }) +export class MyComponent { + private lifecycle = inject(RENDER_LIFECYCLE); + + constructor() { + effect(() => { + const first = this.lifecycle.firstMountAt(); + if (first) { + console.log('First render at', first.at, 'kind:', first.kind); + } + }); + } +} +``` + +## Reset semantics + +`firstMountAt` is sticky for the life of the render context ā€” once set, it does not reset. The remaining four signals update on every relevant event. + +## Privacy + +These signals contain no spec content, no state values, no handler parameters. They are timestamps, counts, and short discriminants (`spec` / `element`, action names from the registered handler bindings) only. The trust contract at [libs/telemetry/README.md](https://github.com/cacheplane/angular-agent-framework/blob/main/libs/telemetry/README.md) applies: **no app telemetry by default.** Subscribing to `RENDER_LIFECYCLE` in your code does not fire any telemetry; what you do with the signal values is your choice. diff --git a/apps/website/src/lib/docs-config.ts b/apps/website/src/lib/docs-config.ts index 8f1afe24b..5d41acff9 100644 --- a/apps/website/src/lib/docs-config.ts +++ b/apps/website/src/lib/docs-config.ts @@ -49,6 +49,7 @@ export const docsConfig: DocsLibrary[] = [ { title: 'Subgraphs', slug: 'subgraphs', section: 'guides' }, { title: 'Testing', slug: 'testing', section: 'guides' }, { title: 'Deployment', slug: 'deployment', section: 'guides' }, + { title: 'Lifecycle Signals', slug: 'lifecycle', section: 'guides' }, ], }, { @@ -99,6 +100,7 @@ export const docsConfig: DocsLibrary[] = [ { title: 'State Store', slug: 'state-store', section: 'guides' }, { title: 'Specs & Elements', slug: 'specs', section: 'guides' }, { title: 'Events & Handlers', slug: 'events', section: 'guides' }, + { title: 'Lifecycle Signals', slug: 'lifecycle', section: 'guides' }, ], }, { @@ -152,6 +154,7 @@ export const docsConfig: DocsLibrary[] = [ { title: 'Streaming', slug: 'streaming', section: 'guides' }, { title: 'Configuration', slug: 'configuration', section: 'guides' }, { title: 'Writing an Adapter', slug: 'writing-an-adapter', section: 'guides' }, + { title: 'Lifecycle Signals', slug: 'lifecycle', section: 'guides' }, ], }, { diff --git a/cockpit/chat/a2ui/angular/project.json b/cockpit/chat/a2ui/angular/project.json index 5bd06c664..683c36939 100644 --- a/cockpit/chat/a2ui/angular/project.json +++ b/cockpit/chat/a2ui/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/a2ui/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/a2ui/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-a2ui-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-a2ui-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-a2ui-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-a2ui-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/a2ui/angular/src/main.cockpit.ts b/cockpit/chat/a2ui/angular/src/main.cockpit.ts new file mode 100644 index 000000000..e5b09d22e --- /dev/null +++ b/cockpit/chat/a2ui/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { A2uiComponent } from './app/a2ui.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(A2uiComponent, appConfig); diff --git a/cockpit/chat/debug/angular/project.json b/cockpit/chat/debug/angular/project.json index ee6aa37c0..d41edfa9a 100644 --- a/cockpit/chat/debug/angular/project.json +++ b/cockpit/chat/debug/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/debug/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/debug/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-debug-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-debug-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-debug-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-debug-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/debug/angular/src/main.cockpit.ts b/cockpit/chat/debug/angular/src/main.cockpit.ts new file mode 100644 index 000000000..493773d5c --- /dev/null +++ b/cockpit/chat/debug/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { DebugPageComponent } from './app/debug.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(DebugPageComponent, appConfig); diff --git a/cockpit/chat/generative-ui/angular/project.json b/cockpit/chat/generative-ui/angular/project.json index 7b90bb746..fd43d50ef 100644 --- a/cockpit/chat/generative-ui/angular/project.json +++ b/cockpit/chat/generative-ui/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/generative-ui/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/generative-ui/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-generative-ui-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-generative-ui-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-generative-ui-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-generative-ui-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/generative-ui/angular/src/main.cockpit.ts b/cockpit/chat/generative-ui/angular/src/main.cockpit.ts new file mode 100644 index 000000000..3c334e4cc --- /dev/null +++ b/cockpit/chat/generative-ui/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { GenerativeUiComponent } from './app/generative-ui.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(GenerativeUiComponent, appConfig); diff --git a/cockpit/chat/input/angular/project.json b/cockpit/chat/input/angular/project.json index 2d77364dc..6ba960877 100644 --- a/cockpit/chat/input/angular/project.json +++ b/cockpit/chat/input/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/input/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/input/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-input-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-input-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-input-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-input-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/input/angular/src/main.cockpit.ts b/cockpit/chat/input/angular/src/main.cockpit.ts new file mode 100644 index 000000000..3ac6edf78 --- /dev/null +++ b/cockpit/chat/input/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { InputComponent } from './app/input.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(InputComponent, appConfig); diff --git a/cockpit/chat/interrupts/angular/project.json b/cockpit/chat/interrupts/angular/project.json index 4393871d4..18cdd5ef8 100644 --- a/cockpit/chat/interrupts/angular/project.json +++ b/cockpit/chat/interrupts/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/interrupts/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/interrupts/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-interrupts-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-interrupts-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-interrupts-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-interrupts-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/interrupts/angular/src/main.cockpit.ts b/cockpit/chat/interrupts/angular/src/main.cockpit.ts new file mode 100644 index 000000000..31e848d37 --- /dev/null +++ b/cockpit/chat/interrupts/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { InterruptsComponent } from './app/interrupts.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(InterruptsComponent, appConfig); diff --git a/cockpit/chat/messages/angular/project.json b/cockpit/chat/messages/angular/project.json index 405207583..ec13ef09a 100644 --- a/cockpit/chat/messages/angular/project.json +++ b/cockpit/chat/messages/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/messages/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/messages/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-messages-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-messages-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-messages-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-messages-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/messages/angular/src/main.cockpit.ts b/cockpit/chat/messages/angular/src/main.cockpit.ts new file mode 100644 index 000000000..1f89da2db --- /dev/null +++ b/cockpit/chat/messages/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { MessagesComponent } from './app/messages.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(MessagesComponent, appConfig); diff --git a/cockpit/chat/subagents/angular/project.json b/cockpit/chat/subagents/angular/project.json index 89ed44c2f..05ae1af11 100644 --- a/cockpit/chat/subagents/angular/project.json +++ b/cockpit/chat/subagents/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/subagents/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/subagents/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-subagents-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-subagents-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-subagents-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-subagents-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/subagents/angular/src/main.cockpit.ts b/cockpit/chat/subagents/angular/src/main.cockpit.ts new file mode 100644 index 000000000..c540d6b3f --- /dev/null +++ b/cockpit/chat/subagents/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { SubagentsComponent } from './app/subagents.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(SubagentsComponent, appConfig); diff --git a/cockpit/chat/theming/angular/project.json b/cockpit/chat/theming/angular/project.json index d0a34587e..5db69f38b 100644 --- a/cockpit/chat/theming/angular/project.json +++ b/cockpit/chat/theming/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/theming/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/theming/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-theming-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-theming-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-theming-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-theming-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/theming/angular/src/main.cockpit.ts b/cockpit/chat/theming/angular/src/main.cockpit.ts new file mode 100644 index 000000000..12f871a0d --- /dev/null +++ b/cockpit/chat/theming/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { ThemingComponent } from './app/theming.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(ThemingComponent, appConfig); diff --git a/cockpit/chat/threads/angular/project.json b/cockpit/chat/threads/angular/project.json index 5dbf5e131..5b2948700 100644 --- a/cockpit/chat/threads/angular/project.json +++ b/cockpit/chat/threads/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/threads/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/threads/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-threads-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-threads-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-threads-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-threads-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/threads/angular/src/main.cockpit.ts b/cockpit/chat/threads/angular/src/main.cockpit.ts new file mode 100644 index 000000000..822b9a610 --- /dev/null +++ b/cockpit/chat/threads/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { ThreadsComponent } from './app/threads.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(ThreadsComponent, appConfig); diff --git a/cockpit/chat/timeline/angular/project.json b/cockpit/chat/timeline/angular/project.json index f3705700d..d767ed64b 100644 --- a/cockpit/chat/timeline/angular/project.json +++ b/cockpit/chat/timeline/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/timeline/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/timeline/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-timeline-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-timeline-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-timeline-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-timeline-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/timeline/angular/src/main.cockpit.ts b/cockpit/chat/timeline/angular/src/main.cockpit.ts new file mode 100644 index 000000000..dae788aae --- /dev/null +++ b/cockpit/chat/timeline/angular/src/main.cockpit.ts @@ -0,0 +1,9 @@ +// SPDX-License-Identifier: MIT +import { installEmbeddedTheme } from '@ngaf/example-layouts'; +import { appConfig } from './app/app.config'; +import { TimelineComponent } from './app/timeline.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +installEmbeddedTheme(); + +bootstrapWithCockpitHarness(TimelineComponent, appConfig); diff --git a/cockpit/chat/tool-calls/angular/project.json b/cockpit/chat/tool-calls/angular/project.json index 533b9f573..ab2966061 100644 --- a/cockpit/chat/tool-calls/angular/project.json +++ b/cockpit/chat/tool-calls/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/chat/tool-calls/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/chat/tool-calls/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-chat-tool-calls-angular:build:production" }, - "development": { "buildTarget": "cockpit-chat-tool-calls-angular:build:development" } + "development": { "buildTarget": "cockpit-chat-tool-calls-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-chat-tool-calls-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/chat/tool-calls/angular/src/main.cockpit.ts b/cockpit/chat/tool-calls/angular/src/main.cockpit.ts new file mode 100644 index 000000000..32e0b253c --- /dev/null +++ b/cockpit/chat/tool-calls/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { ToolCallsComponent } from './app/tool-calls.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(ToolCallsComponent, appConfig); diff --git a/cockpit/deep-agents/filesystem/angular/project.json b/cockpit/deep-agents/filesystem/angular/project.json index 8dd826f99..61aa3d5d2 100644 --- a/cockpit/deep-agents/filesystem/angular/project.json +++ b/cockpit/deep-agents/filesystem/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/deep-agents/filesystem/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/deep-agents/filesystem/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-deep-agents-filesystem-angular:build:production" }, - "development": { "buildTarget": "cockpit-deep-agents-filesystem-angular:build:development" } + "development": { "buildTarget": "cockpit-deep-agents-filesystem-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-deep-agents-filesystem-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/deep-agents/filesystem/angular/src/main.cockpit.ts b/cockpit/deep-agents/filesystem/angular/src/main.cockpit.ts new file mode 100644 index 000000000..322cb81f1 --- /dev/null +++ b/cockpit/deep-agents/filesystem/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { FilesystemComponent } from './app/filesystem.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(FilesystemComponent, appConfig); diff --git a/cockpit/deep-agents/memory/angular/project.json b/cockpit/deep-agents/memory/angular/project.json index 5cfb65722..0c8c2373d 100644 --- a/cockpit/deep-agents/memory/angular/project.json +++ b/cockpit/deep-agents/memory/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/deep-agents/memory/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/deep-agents/memory/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-deep-agents-memory-angular:build:production" }, - "development": { "buildTarget": "cockpit-deep-agents-memory-angular:build:development" } + "development": { "buildTarget": "cockpit-deep-agents-memory-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-deep-agents-memory-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/deep-agents/memory/angular/src/main.cockpit.ts b/cockpit/deep-agents/memory/angular/src/main.cockpit.ts new file mode 100644 index 000000000..099d1abd8 --- /dev/null +++ b/cockpit/deep-agents/memory/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { MemoryComponent } from './app/memory.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(MemoryComponent, appConfig); diff --git a/cockpit/deep-agents/planning/angular/project.json b/cockpit/deep-agents/planning/angular/project.json index 993b8ac0f..fa69589b4 100644 --- a/cockpit/deep-agents/planning/angular/project.json +++ b/cockpit/deep-agents/planning/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/deep-agents/planning/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/deep-agents/planning/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-deep-agents-planning-angular:build:production" }, - "development": { "buildTarget": "cockpit-deep-agents-planning-angular:build:development" } + "development": { "buildTarget": "cockpit-deep-agents-planning-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-deep-agents-planning-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/deep-agents/planning/angular/src/main.cockpit.ts b/cockpit/deep-agents/planning/angular/src/main.cockpit.ts new file mode 100644 index 000000000..9784f7f2c --- /dev/null +++ b/cockpit/deep-agents/planning/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { PlanningComponent } from './app/planning.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(PlanningComponent, appConfig); diff --git a/cockpit/deep-agents/sandboxes/angular/project.json b/cockpit/deep-agents/sandboxes/angular/project.json index 05f75baa3..1a7f94061 100644 --- a/cockpit/deep-agents/sandboxes/angular/project.json +++ b/cockpit/deep-agents/sandboxes/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/deep-agents/sandboxes/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/deep-agents/sandboxes/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-deep-agents-sandboxes-angular:build:production" }, - "development": { "buildTarget": "cockpit-deep-agents-sandboxes-angular:build:development" } + "development": { "buildTarget": "cockpit-deep-agents-sandboxes-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-deep-agents-sandboxes-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/deep-agents/sandboxes/angular/src/main.cockpit.ts b/cockpit/deep-agents/sandboxes/angular/src/main.cockpit.ts new file mode 100644 index 000000000..304dfef9b --- /dev/null +++ b/cockpit/deep-agents/sandboxes/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { SandboxesComponent } from './app/sandboxes.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(SandboxesComponent, appConfig); diff --git a/cockpit/deep-agents/skills/angular/project.json b/cockpit/deep-agents/skills/angular/project.json index b8c23e713..a22efa570 100644 --- a/cockpit/deep-agents/skills/angular/project.json +++ b/cockpit/deep-agents/skills/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/deep-agents/skills/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/deep-agents/skills/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-deep-agents-skills-angular:build:production" }, - "development": { "buildTarget": "cockpit-deep-agents-skills-angular:build:development" } + "development": { "buildTarget": "cockpit-deep-agents-skills-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-deep-agents-skills-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/deep-agents/skills/angular/src/main.cockpit.ts b/cockpit/deep-agents/skills/angular/src/main.cockpit.ts new file mode 100644 index 000000000..5dccc296b --- /dev/null +++ b/cockpit/deep-agents/skills/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { SkillsComponent } from './app/skills.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(SkillsComponent, appConfig); diff --git a/cockpit/deep-agents/subagents/angular/project.json b/cockpit/deep-agents/subagents/angular/project.json index 0183443b8..41afc7aea 100644 --- a/cockpit/deep-agents/subagents/angular/project.json +++ b/cockpit/deep-agents/subagents/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/deep-agents/subagents/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/deep-agents/subagents/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-deep-agents-subagents-angular:build:production" }, - "development": { "buildTarget": "cockpit-deep-agents-subagents-angular:build:development" } + "development": { "buildTarget": "cockpit-deep-agents-subagents-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-deep-agents-subagents-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/deep-agents/subagents/angular/src/main.cockpit.ts b/cockpit/deep-agents/subagents/angular/src/main.cockpit.ts new file mode 100644 index 000000000..c540d6b3f --- /dev/null +++ b/cockpit/deep-agents/subagents/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { SubagentsComponent } from './app/subagents.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(SubagentsComponent, appConfig); diff --git a/cockpit/langgraph/deployment-runtime/angular/project.json b/cockpit/langgraph/deployment-runtime/angular/project.json index 3d7ed8cc4..c3be26f33 100644 --- a/cockpit/langgraph/deployment-runtime/angular/project.json +++ b/cockpit/langgraph/deployment-runtime/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/deployment-runtime/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/deployment-runtime/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-deployment-runtime-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-deployment-runtime-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-deployment-runtime-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-deployment-runtime-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/deployment-runtime/angular/src/main.cockpit.ts b/cockpit/langgraph/deployment-runtime/angular/src/main.cockpit.ts new file mode 100644 index 000000000..ea3a42422 --- /dev/null +++ b/cockpit/langgraph/deployment-runtime/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { DeploymentRuntimeComponent } from './app/deployment-runtime.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(DeploymentRuntimeComponent, appConfig); diff --git a/cockpit/langgraph/durable-execution/angular/project.json b/cockpit/langgraph/durable-execution/angular/project.json index 50d1d8acd..87f52807d 100644 --- a/cockpit/langgraph/durable-execution/angular/project.json +++ b/cockpit/langgraph/durable-execution/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/durable-execution/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/durable-execution/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-durable-execution-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-durable-execution-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-durable-execution-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-durable-execution-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/durable-execution/angular/src/main.cockpit.ts b/cockpit/langgraph/durable-execution/angular/src/main.cockpit.ts new file mode 100644 index 000000000..cc33d8000 --- /dev/null +++ b/cockpit/langgraph/durable-execution/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { DurableExecutionComponent } from './app/durable-execution.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(DurableExecutionComponent, appConfig); diff --git a/cockpit/langgraph/interrupts/angular/project.json b/cockpit/langgraph/interrupts/angular/project.json index 8a5213fcd..13df9b906 100644 --- a/cockpit/langgraph/interrupts/angular/project.json +++ b/cockpit/langgraph/interrupts/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/interrupts/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/interrupts/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-interrupts-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-interrupts-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-interrupts-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-interrupts-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/interrupts/angular/src/main.cockpit.ts b/cockpit/langgraph/interrupts/angular/src/main.cockpit.ts new file mode 100644 index 000000000..31e848d37 --- /dev/null +++ b/cockpit/langgraph/interrupts/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { InterruptsComponent } from './app/interrupts.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(InterruptsComponent, appConfig); diff --git a/cockpit/langgraph/memory/angular/project.json b/cockpit/langgraph/memory/angular/project.json index d8b99784f..3a516c7ca 100644 --- a/cockpit/langgraph/memory/angular/project.json +++ b/cockpit/langgraph/memory/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/memory/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/memory/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-memory-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-memory-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-memory-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-memory-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/memory/angular/src/main.cockpit.ts b/cockpit/langgraph/memory/angular/src/main.cockpit.ts new file mode 100644 index 000000000..099d1abd8 --- /dev/null +++ b/cockpit/langgraph/memory/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { MemoryComponent } from './app/memory.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(MemoryComponent, appConfig); diff --git a/cockpit/langgraph/persistence/angular/project.json b/cockpit/langgraph/persistence/angular/project.json index a07043cb1..57584e20b 100644 --- a/cockpit/langgraph/persistence/angular/project.json +++ b/cockpit/langgraph/persistence/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/persistence/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/persistence/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-persistence-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-persistence-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-persistence-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-persistence-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/persistence/angular/src/main.cockpit.ts b/cockpit/langgraph/persistence/angular/src/main.cockpit.ts new file mode 100644 index 000000000..8a2311ac4 --- /dev/null +++ b/cockpit/langgraph/persistence/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { PersistenceComponent } from './app/persistence.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(PersistenceComponent, appConfig); diff --git a/cockpit/langgraph/streaming/angular/project.json b/cockpit/langgraph/streaming/angular/project.json index 6f75b03d1..65fad2213 100644 --- a/cockpit/langgraph/streaming/angular/project.json +++ b/cockpit/langgraph/streaming/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/streaming/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/streaming/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-streaming-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-streaming-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-streaming-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-streaming-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/streaming/angular/src/main.cockpit.ts b/cockpit/langgraph/streaming/angular/src/main.cockpit.ts new file mode 100644 index 000000000..601420966 --- /dev/null +++ b/cockpit/langgraph/streaming/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { StreamingComponent } from './app/streaming.component'; +import { appConfig } from './app/app.config'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(StreamingComponent, appConfig); diff --git a/cockpit/langgraph/subgraphs/angular/project.json b/cockpit/langgraph/subgraphs/angular/project.json index 0bf30c402..cce23df7a 100644 --- a/cockpit/langgraph/subgraphs/angular/project.json +++ b/cockpit/langgraph/subgraphs/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/subgraphs/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/subgraphs/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-subgraphs-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-subgraphs-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-subgraphs-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-subgraphs-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/subgraphs/angular/src/main.cockpit.ts b/cockpit/langgraph/subgraphs/angular/src/main.cockpit.ts new file mode 100644 index 000000000..a2ec3774b --- /dev/null +++ b/cockpit/langgraph/subgraphs/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { SubgraphsComponent } from './app/subgraphs.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(SubgraphsComponent, appConfig); diff --git a/cockpit/langgraph/time-travel/angular/project.json b/cockpit/langgraph/time-travel/angular/project.json index 771628a58..2a8cd3f60 100644 --- a/cockpit/langgraph/time-travel/angular/project.json +++ b/cockpit/langgraph/time-travel/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/langgraph/time-travel/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/langgraph/time-travel/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-langgraph-time-travel-angular:build:production" }, - "development": { "buildTarget": "cockpit-langgraph-time-travel-angular:build:development" } + "development": { "buildTarget": "cockpit-langgraph-time-travel-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-langgraph-time-travel-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/langgraph/time-travel/angular/src/main.cockpit.ts b/cockpit/langgraph/time-travel/angular/src/main.cockpit.ts new file mode 100644 index 000000000..fc35f2f5f --- /dev/null +++ b/cockpit/langgraph/time-travel/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { TimeTravelComponent } from './app/time-travel.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(TimeTravelComponent, appConfig); diff --git a/cockpit/render/computed-functions/angular/project.json b/cockpit/render/computed-functions/angular/project.json index bf070de8e..c959cf433 100644 --- a/cockpit/render/computed-functions/angular/project.json +++ b/cockpit/render/computed-functions/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/render/computed-functions/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/render/computed-functions/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-render-computed-functions-angular:build:production" }, - "development": { "buildTarget": "cockpit-render-computed-functions-angular:build:development" } + "development": { "buildTarget": "cockpit-render-computed-functions-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-render-computed-functions-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/render/computed-functions/angular/src/main.cockpit.ts b/cockpit/render/computed-functions/angular/src/main.cockpit.ts new file mode 100644 index 000000000..76b49a15f --- /dev/null +++ b/cockpit/render/computed-functions/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { ComputedFunctionsComponent } from './app/computed-functions.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(ComputedFunctionsComponent, appConfig); diff --git a/cockpit/render/element-rendering/angular/project.json b/cockpit/render/element-rendering/angular/project.json index c92192f8a..1c1ea31d0 100644 --- a/cockpit/render/element-rendering/angular/project.json +++ b/cockpit/render/element-rendering/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/render/element-rendering/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/render/element-rendering/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-render-element-rendering-angular:build:production" }, - "development": { "buildTarget": "cockpit-render-element-rendering-angular:build:development" } + "development": { "buildTarget": "cockpit-render-element-rendering-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-render-element-rendering-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/render/element-rendering/angular/src/main.cockpit.ts b/cockpit/render/element-rendering/angular/src/main.cockpit.ts new file mode 100644 index 000000000..bb6b30d56 --- /dev/null +++ b/cockpit/render/element-rendering/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { ElementRenderingComponent } from './app/element-rendering.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(ElementRenderingComponent, appConfig); diff --git a/cockpit/render/registry/angular/project.json b/cockpit/render/registry/angular/project.json index c771d1fa5..2d7c482c8 100644 --- a/cockpit/render/registry/angular/project.json +++ b/cockpit/render/registry/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/render/registry/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/render/registry/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-render-registry-angular:build:production" }, - "development": { "buildTarget": "cockpit-render-registry-angular:build:development" } + "development": { "buildTarget": "cockpit-render-registry-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-render-registry-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/render/registry/angular/src/main.cockpit.ts b/cockpit/render/registry/angular/src/main.cockpit.ts new file mode 100644 index 000000000..333c89c11 --- /dev/null +++ b/cockpit/render/registry/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { RegistryComponent } from './app/registry.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(RegistryComponent, appConfig); diff --git a/cockpit/render/repeat-loops/angular/project.json b/cockpit/render/repeat-loops/angular/project.json index b1127da91..8c02340ae 100644 --- a/cockpit/render/repeat-loops/angular/project.json +++ b/cockpit/render/repeat-loops/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/render/repeat-loops/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/render/repeat-loops/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-render-repeat-loops-angular:build:production" }, - "development": { "buildTarget": "cockpit-render-repeat-loops-angular:build:development" } + "development": { "buildTarget": "cockpit-render-repeat-loops-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-render-repeat-loops-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/render/repeat-loops/angular/src/main.cockpit.ts b/cockpit/render/repeat-loops/angular/src/main.cockpit.ts new file mode 100644 index 000000000..0c1a797a9 --- /dev/null +++ b/cockpit/render/repeat-loops/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { RepeatLoopsComponent } from './app/repeat-loops.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(RepeatLoopsComponent, appConfig); diff --git a/cockpit/render/spec-rendering/angular/project.json b/cockpit/render/spec-rendering/angular/project.json index f53637900..dd23e97c6 100644 --- a/cockpit/render/spec-rendering/angular/project.json +++ b/cockpit/render/spec-rendering/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/render/spec-rendering/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/render/spec-rendering/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-render-spec-rendering-angular:build:production" }, - "development": { "buildTarget": "cockpit-render-spec-rendering-angular:build:development" } + "development": { "buildTarget": "cockpit-render-spec-rendering-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-render-spec-rendering-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/render/spec-rendering/angular/src/main.cockpit.ts b/cockpit/render/spec-rendering/angular/src/main.cockpit.ts new file mode 100644 index 000000000..6ffd89808 --- /dev/null +++ b/cockpit/render/spec-rendering/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { SpecRenderingComponent } from './app/spec-rendering.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(SpecRenderingComponent, appConfig); diff --git a/cockpit/render/state-management/angular/project.json b/cockpit/render/state-management/angular/project.json index b44f95870..906da48d9 100644 --- a/cockpit/render/state-management/angular/project.json +++ b/cockpit/render/state-management/angular/project.json @@ -34,6 +34,14 @@ "with": "cockpit/render/state-management/angular/src/environments/environment.development.ts" } ] + }, + "cockpit": { + "budgets": [ + { "type": "initial", "maximumWarning": "500kb", "maximumError": "1mb" }, + { "type": "anyComponentStyle", "maximumWarning": "4kb", "maximumError": "8kb" } + ], + "outputHashing": "none", + "browser": "cockpit/render/state-management/angular/src/main.cockpit.ts" } }, "defaultConfiguration": "production" @@ -43,7 +51,8 @@ "executor": "@angular/build:dev-server", "configurations": { "production": { "buildTarget": "cockpit-render-state-management-angular:build:production" }, - "development": { "buildTarget": "cockpit-render-state-management-angular:build:development" } + "development": { "buildTarget": "cockpit-render-state-management-angular:build:development" }, + "cockpit": { "buildTarget": "cockpit-render-state-management-angular:build:cockpit" } }, "defaultConfiguration": "development", "options": { diff --git a/cockpit/render/state-management/angular/src/main.cockpit.ts b/cockpit/render/state-management/angular/src/main.cockpit.ts new file mode 100644 index 000000000..f0c3c4e0f --- /dev/null +++ b/cockpit/render/state-management/angular/src/main.cockpit.ts @@ -0,0 +1,6 @@ +// SPDX-License-Identifier: MIT +import { appConfig } from './app/app.config'; +import { StateManagementComponent } from './app/state-management.component'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(StateManagementComponent, appConfig); diff --git a/docs/gtm/taxonomy.md b/docs/gtm/taxonomy.md index e6ff2e83d..7dc2d3caf 100644 --- a/docs/gtm/taxonomy.md +++ b/docs/gtm/taxonomy.md @@ -49,16 +49,25 @@ The standard PostHog `$pageview` event is used as-is across all three surfaces. ## Cockpit (activation surface) -| Event | When | -|------------------------------------------------|--------------------------------------------------------| -| `cockpit:recipe_start` | Recipe page loaded with intent (`?source=` present) | -| `cockpit:install_command_copied` | Install command copied | -| `cockpit:transport_connected` | LangGraph/AG-UI/custom adapter wired in tour | -| `cockpit:chat_first_message` | First user message sent in cockpit chat | -| `cockpit:thread_persisted` | Thread saved (re-load demonstrated) | -| `cockpit:interrupt_handled` | Human-approval interrupt completed | -| `cockpit:generative_component_rendered` | One generative Angular component rendered | -| `cockpit:six_signals_complete` | All six signals fired within 30 min for one session | +| Event | When | +|------------------------------------------------|-----------------------------------------------------------------| +| `cockpit:recipe_opened` | Sidebar capability link clicked | +| `cockpit:mode_switched` | Run/Code/Docs/API tab change | +| `cockpit:code_copied` | Copy click in code mode, doc snippet, or agentic-prompt block | +| `cockpit:transport_connected` | LangGraph/AG-UI/custom adapter wired in iframe | +| `cockpit:chat_first_message` | First user message sent in cockpit chat | +| `cockpit:thread_persisted` | Thread saved (re-load demonstrated) | +| `cockpit:interrupt_handled` | Human-approval interrupt completed | +| `cockpit:generative_component_rendered` | One generative Angular component rendered | +| `cockpit:activation_complete` | All five activation signals fired within 30 min for one session | + +The five activation signals (whose union fires `cockpit:activation_complete`) are +`transport_connected`, `chat_first_message`, `thread_persisted`, `interrupt_handled`, +and `generative_component_rendered`. The shell events (`recipe_opened`, +`mode_switched`, `code_copied`) are context for the funnel ā€” they fire before +or alongside the activation signals but are not part of the five-step rollup. +`ngaf:postinstall` is a separate top-of-funnel chart, uncorrelated to cockpit +sessions by design. ## ngaf (library telemetry) @@ -135,3 +144,5 @@ This file is human-edited. When events are added/renamed/removed, update the aff | Date | Change | |------------|--------| | 2026-05-13 | Initial draft per Spec 0. | +| 2026-05-15 | Drop cockpit:install_command_copied, rename cockpit:six_signals_complete ā†’ cockpit:activation_complete (Spec 1C). | +| 2026-05-15 | Cockpit shell events: rename `recipe_start` ā†’ `recipe_opened`; add `mode_switched` and `code_copied` (Spec 1C implementation). | diff --git a/docs/superpowers/plans/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation.md b/docs/superpowers/plans/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation.md new file mode 100644 index 000000000..b4db10830 --- /dev/null +++ b/docs/superpowers/plans/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation.md @@ -0,0 +1,2816 @@ +# Spec 1C ā€” Cockpit Instrumentation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Instrument cockpit's three surfaces (React shell + 32 Angular iframes + cross-frame correlation) so the developer-funnel dashboard from Spec 1A populates with real cohort data, while keeping example reference code pristine. + +**Architecture:** Architecture B ā€” public `CHAT_LIFECYCLE`/`AGENT_LIFECYCLE`/`RENDER_LIFECYCLE` `InjectionToken`s in the three `@ngaf/*` libs; private `@ngaf/cockpit-telemetry` adapter subscribes and fires `cockpit:*` events via posthog-js direct (memory persistence, parent-provided distinct_id). React shell instruments its own surface using posthog-js direct. Build-time `main.cockpit.ts` entry override keeps example reference code untouched. + +**Tech Stack:** TypeScript via `tsx`; Angular 20/21 (Signals + DI); `posthog-js` (^1.373.0); Vitest (existing repo convention for libs); jsdom per-spec for Angular DI tests; Nx 21.x; Next.js 16 for the cockpit shell. + +--- + +## Context for the implementer + +- **Spec:** `docs/superpowers/specs/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation-design.md` ā€” read Ā§4 (architecture), Ā§5 (lifecycle interfaces), Ā§6 (cockpit-telemetry internals), Ā§7 (React shell), Ā§8 (main.cockpit.ts), Ā§9 (cross-frame correlation), Ā§10 (testing strategy) before starting. +- **Trust contract:** `libs/telemetry/README.md` (post-PR-#328). Use "no app telemetry by default" framing in any new docs. +- **Test infra:** Vitest with `// @vitest-environment jsdom` pragma on browser specs that need DOM. Existing libs (chat, langgraph) use the same pattern ā€” see `libs/chat/vite.config.mts`. +- **TDD discipline:** every code task follows write-test ā†’ run-and-fail ā†’ implement ā†’ run-and-pass ā†’ commit. Subagents must observe the failing test BEFORE implementing. +- **Commit format:** conventional commits. Examples: `feat(chat): add CHAT_LIFECYCLE token + signals`, `test(cockpit-telemetry): add activation aggregator window math tests`, `feat(cockpit): instrument sidebar with cockpit:recipe_opened`. +- **Per-task commit:** one task = one commit. The plan progresses by checking off tasks and committing. +- **Cockpit dev server:** `nx run cockpit:serve` (port 4201). Each Angular example serves on its own port via `nx run cockpit:serve-`. +- **Angular peer dep:** `^20.0.0 || ^21.0.0` (matches existing `@ngaf/*` libs). +- **PR #328 is on main** at `ba4904f2`. The plan assumes this is in place ā€” `@ngaf/telemetry` no longer bundles posthog-node, `/api/ingest` proxy exists, etc. + +## File structure (locked) + +``` +NEW +ā”œā”€ā”€ libs/chat/src/lib/lifecycle.ts # Phase 0 +ā”œā”€ā”€ libs/chat/src/lib/lifecycle.spec.ts # Phase 0 +ā”œā”€ā”€ libs/langgraph/src/lib/lifecycle.ts # Phase 0 +ā”œā”€ā”€ libs/langgraph/src/lib/lifecycle.spec.ts # Phase 0 +ā”œā”€ā”€ libs/render/src/lib/lifecycle.ts # Phase 0 +ā”œā”€ā”€ libs/render/src/lib/render-lifecycle.service.ts # Phase 0 +ā”œā”€ā”€ libs/render/src/lib/lifecycle.spec.ts # Phase 0 +ā”‚ +ā”œā”€ā”€ libs/cockpit-telemetry/ # Phase 1 (entire dir) +ā”‚ ā”œā”€ā”€ package.json +ā”‚ ā”œā”€ā”€ project.json +ā”‚ ā”œā”€ā”€ tsconfig.json +ā”‚ ā”œā”€ā”€ tsconfig.lib.json +ā”‚ ā”œā”€ā”€ tsconfig.spec.json +ā”‚ ā”œā”€ā”€ ng-package.json +ā”‚ ā”œā”€ā”€ eslint.config.mjs +ā”‚ ā”œā”€ā”€ vite.config.mts +ā”‚ ā”œā”€ā”€ README.md +ā”‚ ā”œā”€ā”€ src/ +ā”‚ ā”‚ ā”œā”€ā”€ index.ts +ā”‚ ā”‚ ā”œā”€ā”€ public-api.ts +ā”‚ ā”‚ ā”œā”€ā”€ test-setup.ts +ā”‚ ā”‚ ā”œā”€ā”€ lib/ +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ tokens.ts +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ events.ts +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ distinct-id.ts + distinct-id.spec.ts +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ activation-aggregator.ts + activation-aggregator.spec.ts +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ cockpit-telemetry.service.ts + cockpit-telemetry.service.spec.ts +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ provide-cockpit-telemetry.ts +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ harness.ts + harness.spec.ts +ā”‚ ā”‚ ā”‚ ā””ā”€ā”€ browser-silence.spec.ts (permanent) +ā”‚ +ā”œā”€ā”€ apps/cockpit/instrumentation-client.ts # Phase 2 +ā”œā”€ā”€ apps/cockpit/src/lib/analytics/ # Phase 2 (entire dir) +ā”‚ ā”œā”€ā”€ distinct-id.ts + distinct-id.spec.ts +ā”‚ ā”œā”€ā”€ properties.ts + properties.spec.ts +ā”‚ ā”œā”€ā”€ events.ts +ā”‚ ā””ā”€ā”€ client.ts + client.spec.ts +ā”‚ +ā”œā”€ā”€ cockpit///angular/src/main.cockpit.ts # Phase 3 (streaming) + Phase 4 (31 more) +ā”‚ +ā”œā”€ā”€ apps/website/src/content/docs/chat/lifecycle.md # Phase 5 +ā”œā”€ā”€ apps/website/src/content/docs/langgraph/lifecycle.md # Phase 5 +ā”œā”€ā”€ apps/website/src/content/docs/render/lifecycle.md # Phase 5 +ā”‚ +MODIFIED +ā”œā”€ā”€ libs/chat/src/lib/compositions/chat/chat.component.ts # populates ChatLifecycle +ā”œā”€ā”€ libs/chat/src/public-api.ts # exports CHAT_LIFECYCLE +ā”œā”€ā”€ libs/langgraph/src/lib/agent.fn.ts # populates AgentLifecycle +ā”œā”€ā”€ libs/langgraph/src/public-api.ts # exports AGENT_LIFECYCLE +ā”œā”€ā”€ libs/render/src/lib/provide-render.ts # provides RENDER_LIFECYCLE +ā”œā”€ā”€ libs/render/src/public-api.ts # exports RENDER_LIFECYCLE +ā”‚ +ā”œā”€ā”€ apps/cockpit/src/components/sidebar/sidebar.tsx # fires cockpit:recipe_opened +ā”œā”€ā”€ apps/cockpit/src/components/modes/mode-switcher.tsx # fires cockpit:mode_switched +ā”œā”€ā”€ apps/cockpit/src/components/code-mode/code-mode.tsx # fires cockpit:code_copied +ā”œā”€ā”€ apps/cockpit/src/components/narrative-docs/narrative-docs.tsx # fires cockpit:code_copied +ā”œā”€ā”€ apps/cockpit/src/components/run-mode/run-mode.tsx # appends URL params to iframe src +ā”œā”€ā”€ apps/cockpit/project.json # serve- targets use cockpit config +ā”‚ +ā”œā”€ā”€ cockpit///angular/project.json # 32 files modified ā€” add cockpit build config +ā”‚ +ā”œā”€ā”€ tsconfig.base.json # path alias for @ngaf/cockpit-telemetry +ā”œā”€ā”€ nx.json # add cockpit-telemetry to project list (if needed) +ā”‚ +ā”œā”€ā”€ docs/gtm/taxonomy.md # Phase 6: drop install_command_copied, rename activation event +ā”œā”€ā”€ tools/posthog/insights/six-signal-activation-funnel.json # Phase 6: rename to activation-funnel.json + update steps +ā”œā”€ā”€ tools/posthog/dashboards/developer-funnel.json # Phase 6: reference renamed insight slug +``` + +--- + +## Phase 0 ā€” Library lifecycle additions (~21 tests) + +Three coordinated changes to publishable libs. Each lib joins the fixed-version group's next bump. Implementations are additive ā€” no existing API breaks. + +### Task 0.1: `@ngaf/chat` lifecycle interface + token + +**Files:** +- Create: `libs/chat/src/lib/lifecycle.ts` + +- [ ] **Step 1: Create the lifecycle interface + token** + +```typescript +// libs/chat/src/lib/lifecycle.ts +import { InjectionToken, Signal } from '@angular/core'; + +export interface ChatLifecycle { + /** True after `` initializes with a non-null agent binding. */ + readonly componentReady: Signal; + /** True after the first user submit. Sticky for the life of the chat instance ā€” does NOT reset on clearThread. */ + readonly firstMessageSent: Signal; + /** Count of user submits. Resets on clearThread. */ + readonly messageCount: Signal; + /** Epoch ms of the most recent user submit. Resets on clearThread. */ + readonly inputSubmittedAt: Signal; +} + +export const CHAT_LIFECYCLE = new InjectionToken('CHAT_LIFECYCLE'); +``` + +- [ ] **Step 2: Export from public-api.ts** + +Open `libs/chat/src/public-api.ts` and add: + +```typescript +export { CHAT_LIFECYCLE } from './lib/lifecycle'; +export type { ChatLifecycle } from './lib/lifecycle'; +``` + +- [ ] **Step 3: Build to confirm no compile errors** + +Run: +```bash +npx nx run chat:build +``` + +Expected: build succeeds. + +- [ ] **Step 4: Commit** + +```bash +git add libs/chat/src/lib/lifecycle.ts libs/chat/src/public-api.ts +git commit -m "$(cat <<'EOF' +feat(chat): add CHAT_LIFECYCLE InjectionToken + interface + +Public API addition for cockpit-telemetry (and other consumers) to +subscribe to per-instance chat lifecycle signals. componentReady, +firstMessageSent (sticky), messageCount and inputSubmittedAt (reset on +clearThread). Token only; wiring lands in next task. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +### Task 0.2: Wire CHAT_LIFECYCLE in chat.component.ts + TDD + +**Files:** +- Modify: `libs/chat/src/lib/compositions/chat/chat.component.ts` +- Create: `libs/chat/src/lib/lifecycle.spec.ts` + +- [ ] **Step 1: Write the failing test** + +Create `libs/chat/src/lib/lifecycle.spec.ts`: + +```typescript +// @vitest-environment jsdom +import { describe, test, expect, beforeEach } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { ChatComponent } from './compositions/chat/chat.component'; +import { CHAT_LIFECYCLE, type ChatLifecycle } from './lifecycle'; +import { agent } from '@ngaf/langgraph'; +import { MockAgentTransport } from '@ngaf/langgraph'; + +describe('ChatLifecycle integration', () => { + let lifecycle: ChatLifecycle; + let chatRef: any; + + beforeEach(() => { + TestBed.configureTestingModule({ + providers: [ + // Mock agent harness + ], + }); + const fixture = TestBed.createComponent(ChatComponent); + chatRef = fixture.componentInstance; + fixture.componentRef.setInput('agent', agent({ + transport: new MockAgentTransport(), + })); + fixture.detectChanges(); + lifecycle = TestBed.inject(CHAT_LIFECYCLE); + }); + + test('componentReady is true after ChatComponent initializes with an agent', () => { + expect(lifecycle.componentReady()).toBe(true); + }); + + test('firstMessageSent starts false', () => { + expect(lifecycle.firstMessageSent()).toBe(false); + }); + + test('firstMessageSent flips to true after first submitMessage and stays true', () => { + chatRef.submitMessage('hello'); + expect(lifecycle.firstMessageSent()).toBe(true); + chatRef.submitMessage('again'); + expect(lifecycle.firstMessageSent()).toBe(true); + }); + + test('messageCount increments on each submit', () => { + chatRef.submitMessage('one'); + chatRef.submitMessage('two'); + chatRef.submitMessage('three'); + expect(lifecycle.messageCount()).toBe(3); + }); + + test('messageCount resets on clearThread but firstMessageSent stays true', () => { + chatRef.submitMessage('one'); + chatRef.clearThread(); + expect(lifecycle.messageCount()).toBe(0); + expect(lifecycle.firstMessageSent()).toBe(true); + }); + + test('inputSubmittedAt updates on submit and resets to null on clearThread', () => { + expect(lifecycle.inputSubmittedAt()).toBe(null); + chatRef.submitMessage('one'); + expect(lifecycle.inputSubmittedAt()).toBeGreaterThan(0); + chatRef.clearThread(); + expect(lifecycle.inputSubmittedAt()).toBe(null); + }); +}); +``` + +- [ ] **Step 2: Run, see fail** + +```bash +npx nx run chat:test -- --reporter=verbose --no-coverage --testPathPattern=lifecycle.spec +``` + +Expected: tests fail with "CHAT_LIFECYCLE not provided" or similar. + +- [ ] **Step 3: Implement wiring in chat.component.ts** + +Open `libs/chat/src/lib/compositions/chat/chat.component.ts`. Find the imports and add: + +```typescript +import { signal } from '@angular/core'; +import { CHAT_LIFECYCLE, type ChatLifecycle } from '../../lifecycle'; +``` + +Inside the `@Component` decorator, add to `providers`: + +```typescript +@Component({ + // ... existing selector, standalone, imports, template + providers: [ + // existing providers... + { + provide: CHAT_LIFECYCLE, + useFactory: () => { + const componentReady = signal(false); + const firstMessageSent = signal(false); + const messageCount = signal(0); + const inputSubmittedAt = signal(null); + return { + componentReady: componentReady.asReadonly(), + firstMessageSent: firstMessageSent.asReadonly(), + messageCount: messageCount.asReadonly(), + inputSubmittedAt: inputSubmittedAt.asReadonly(), + // @internal ā€” used by ChatComponent to populate + _internal: { componentReady, firstMessageSent, messageCount, inputSubmittedAt }, + } as ChatLifecycle & { _internal: any }; + }, + }, + ], + // ... +}) +``` + +Inject the lifecycle in the component constructor: + +```typescript +private lifecycle = inject(CHAT_LIFECYCLE) as ChatLifecycle & { _internal: any }; +``` + +In `ngOnInit` (or the equivalent init effect ā€” match existing pattern): + +```typescript +// In the init effect/ngOnInit, after agent is resolved +this.lifecycle._internal.componentReady.set(true); +``` + +Modify `submitMessage()`: + +```typescript +submitMessage(text: string): void { + // ... existing submit logic + if (!this.lifecycle._internal.firstMessageSent()) { + this.lifecycle._internal.firstMessageSent.set(true); + } + this.lifecycle._internal.messageCount.update((c) => c + 1); + this.lifecycle._internal.inputSubmittedAt.set(Date.now()); +} +``` + +Modify `clearThread()`: + +```typescript +clearThread(): void { + // ... existing clear logic + this.lifecycle._internal.messageCount.set(0); + this.lifecycle._internal.inputSubmittedAt.set(null); + // firstMessageSent intentionally NOT reset ā€” sticky for life +} +``` + +- [ ] **Step 4: Run, see pass** + +```bash +npx nx run chat:test -- --reporter=verbose --no-coverage --testPathPattern=lifecycle.spec +``` + +Expected: 6 tests passing. + +- [ ] **Step 5: Commit** + +```bash +git add libs/chat/src/lib/lifecycle.spec.ts libs/chat/src/lib/compositions/chat/chat.component.ts +git commit -m "$(cat <<'EOF' +feat(chat): wire CHAT_LIFECYCLE in ChatComponent + +Populates the four lifecycle signals from existing component code +paths: componentReady on init effect, firstMessageSent/messageCount/ +inputSubmittedAt in submitMessage, reset (except sticky firstMessageSent) +in clearThread. 6 tests cover all transitions. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +### Task 0.3: `@ngaf/langgraph` AGENT_LIFECYCLE interface + token + +**Files:** +- Create: `libs/langgraph/src/lib/lifecycle.ts` +- Modify: `libs/langgraph/src/public-api.ts` + +- [ ] **Step 1: Create the lifecycle interface + token** + +```typescript +// libs/langgraph/src/lib/lifecycle.ts +import { InjectionToken, Signal } from '@angular/core'; + +export interface AgentLifecycle { + /** Epoch ms of the first stream chunk arrival. Resets on clearThread. */ + readonly streamStartedAt: Signal; + /** Epoch ms + classification of the most recent stream error. Resets on clearThread. */ + readonly streamErrorAt: Signal<{ at: number; classification: string } | null>; + /** Epoch ms of the first interrupt$ non-null in this stream. Resets on clearThread. */ + readonly interruptReceivedAt: Signal; + /** Epoch ms of the most recent submit({ interrupt }) call. Resets on clearThread. */ + readonly interruptResolvedAt: Signal; + /** Epoch ms when the agent's "create new thread" branch fired. Resets on clearThread. */ + readonly threadCreatedAt: Signal; + /** Epoch ms when an existing thread was restored from server (proves persistence). Resets on clearThread. */ + readonly threadPersistedAt: Signal; + /** Epoch ms of the first tool call append. Resets on clearThread. */ + readonly toolCallStartedAt: Signal; + /** Epoch ms of the first tool call result transition. Resets on clearThread. */ + readonly toolCallCompletedAt: Signal; +} + +export const AGENT_LIFECYCLE = new InjectionToken('AGENT_LIFECYCLE'); +``` + +- [ ] **Step 2: Export from public-api.ts** + +Append to `libs/langgraph/src/public-api.ts`: + +```typescript +export { AGENT_LIFECYCLE } from './lib/lifecycle'; +export type { AgentLifecycle } from './lib/lifecycle'; +``` + +- [ ] **Step 3: Build to confirm** + +```bash +npx nx run langgraph:build +``` + +Expected: build succeeds. + +- [ ] **Step 4: Commit** + +```bash +git add libs/langgraph/src/lib/lifecycle.ts libs/langgraph/src/public-api.ts +git commit -m "$(cat <<'EOF' +feat(langgraph): add AGENT_LIFECYCLE InjectionToken + interface + +8 lifecycle signals exposing transition timestamps. Wiring lands in +agent.fn.ts in the next task. Three signals (interruptResolvedAt, +threadCreatedAt, threadPersistedAt) require new hook points; five are +derived from existing BehaviorSubjects. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +### Task 0.4: Wire AGENT_LIFECYCLE in agent.fn.ts + TDD + +**Files:** +- Modify: `libs/langgraph/src/lib/agent.fn.ts` +- Create: `libs/langgraph/src/lib/lifecycle.spec.ts` + +- [ ] **Step 1: Write the failing test** + +Create `libs/langgraph/src/lib/lifecycle.spec.ts`: + +```typescript +// @vitest-environment jsdom +import { describe, test, expect, beforeEach } from 'vitest'; +import { TestBed, runInInjectionContext } from '@angular/core/testing'; +import { agent } from './agent.fn'; +import { AGENT_LIFECYCLE, type AgentLifecycle } from './lifecycle'; +import { MockAgentTransport } from './transport/mock-stream.transport'; +import { Injector } from '@angular/core'; + +describe('AgentLifecycle integration', () => { + let lifecycle: AgentLifecycle; + let agentRef: ReturnType; + let injector: Injector; + + beforeEach(() => { + TestBed.configureTestingModule({ providers: [] }); + injector = TestBed.inject(Injector); + runInInjectionContext(injector, () => { + agentRef = agent({ transport: new MockAgentTransport([ + [{ type: 'values', values: { messages: [{ role: 'assistant', content: 'hi' }] } }], + ]) }); + }); + // Lifecycle is provided by agent() factory + lifecycle = injector.get(AGENT_LIFECYCLE); + }); + + test('streamStartedAt is null before any stream', () => { + expect(lifecycle.streamStartedAt()).toBe(null); + }); + + test('streamStartedAt fires on first stream chunk', async () => { + await agentRef.submit({ messages: [{ role: 'user', content: 'hello' }] }); + expect(lifecycle.streamStartedAt()).toBeGreaterThan(0); + }); + + test('interruptReceivedAt fires when interrupt$ becomes non-null', async () => { + runInInjectionContext(injector, () => { + agentRef = agent({ transport: new MockAgentTransport([ + [{ type: 'interrupt', interrupt: { value: 'approve' } as any }], + ]) }); + }); + lifecycle = injector.get(AGENT_LIFECYCLE); + await agentRef.submit({ messages: [{ role: 'user', content: 'go' }] }); + expect(lifecycle.interruptReceivedAt()).toBeGreaterThan(0); + }); + + test('interruptResolvedAt fires on submit({ interrupt })', async () => { + await agentRef.submit({ interrupt: 'approve' as any }); + expect(lifecycle.interruptResolvedAt()).toBeGreaterThan(0); + }); + + test('threadCreatedAt fires on first message with no threadId passed', async () => { + await agentRef.submit({ messages: [{ role: 'user', content: 'go' }] }); + expect(lifecycle.threadCreatedAt()).toBeGreaterThan(0); + }); + + test('threadPersistedAt fires when agent restores from existing threadId', async () => { + runInInjectionContext(injector, () => { + agentRef = agent({ + transport: new MockAgentTransport([]), + threadId: 'existing-thread-123', + }); + }); + lifecycle = injector.get(AGENT_LIFECYCLE); + // Simulate the restore path firing + await agentRef.loadHistory?.(); + expect(lifecycle.threadPersistedAt()).toBeGreaterThan(0); + }); + + test('toolCallStartedAt fires on first toolCalls$ append', async () => { + runInInjectionContext(injector, () => { + agentRef = agent({ transport: new MockAgentTransport([ + [{ type: 'tool_call', toolCall: { id: 't1', name: 'search', args: {} } as any }], + ]) }); + }); + lifecycle = injector.get(AGENT_LIFECYCLE); + await agentRef.submit({ messages: [{ role: 'user', content: 'search' }] }); + expect(lifecycle.toolCallStartedAt()).toBeGreaterThan(0); + }); + + test('toolCallCompletedAt fires on tool call result transition', async () => { + runInInjectionContext(injector, () => { + agentRef = agent({ transport: new MockAgentTransport([ + [{ type: 'tool_call', toolCall: { id: 't1', name: 'search', args: {}, result: 'done' } as any }], + ]) }); + }); + lifecycle = injector.get(AGENT_LIFECYCLE); + await agentRef.submit({ messages: [{ role: 'user', content: 'search' }] }); + expect(lifecycle.toolCallCompletedAt()).toBeGreaterThan(0); + }); + + test('streamErrorAt fires when transport errors', async () => { + runInInjectionContext(injector, () => { + agentRef = agent({ transport: new MockAgentTransport([ + [{ type: 'error', error: 'kaboom' }], + ]) }); + }); + lifecycle = injector.get(AGENT_LIFECYCLE); + await agentRef.submit({ messages: [{ role: 'user', content: 'go' }] }); + expect(lifecycle.streamErrorAt()?.at).toBeGreaterThan(0); + }); + + test('all signals reset to null on clearThread except those marked sticky', async () => { + await agentRef.submit({ messages: [{ role: 'user', content: 'go' }] }); + expect(lifecycle.streamStartedAt()).toBeGreaterThan(0); + await agentRef.clearThread?.(); + expect(lifecycle.streamStartedAt()).toBe(null); + }); +}); +``` + +- [ ] **Step 2: Run, see fail** + +```bash +npx nx run langgraph:test -- --testPathPattern=lifecycle.spec +``` + +Expected: fails ā€” `AGENT_LIFECYCLE` not provided by `agent()`. + +- [ ] **Step 3: Implement wiring in agent.fn.ts** + +Open `libs/langgraph/src/lib/agent.fn.ts`. After the existing BehaviorSubject definitions, add internal lifecycle signal writables: + +```typescript +import { signal, type Signal, inject, InjectionToken, ENVIRONMENT_INITIALIZER } from '@angular/core'; +import { AGENT_LIFECYCLE, type AgentLifecycle } from './lifecycle'; + +// Inside `agent()` factory, alongside existing BehaviorSubjects: +const _streamStartedAt = signal(null); +const _streamErrorAt = signal<{ at: number; classification: string } | null>(null); +const _interruptReceivedAt = signal(null); +const _interruptResolvedAt = signal(null); +const _threadCreatedAt = signal(null); +const _threadPersistedAt = signal(null); +const _toolCallStartedAt = signal(null); +const _toolCallCompletedAt = signal(null); + +const lifecycle: AgentLifecycle = { + streamStartedAt: _streamStartedAt.asReadonly(), + streamErrorAt: _streamErrorAt.asReadonly(), + interruptReceivedAt: _interruptReceivedAt.asReadonly(), + interruptResolvedAt: _interruptResolvedAt.asReadonly(), + threadCreatedAt: _threadCreatedAt.asReadonly(), + threadPersistedAt: _threadPersistedAt.asReadonly(), + toolCallStartedAt: _toolCallStartedAt.asReadonly(), + toolCallCompletedAt: _toolCallCompletedAt.asReadonly(), +}; + +// Provide the lifecycle in the current injector +inject(Injector).get(EnvironmentInjector).providers ??= []; // pseudocode ā€” match existing provider style +``` + +Actually wire via the agent's existing DI integration. The cleanest way: have `agent()` register a provider on its destroyRef-scoped injector. Inside `agent()`: + +```typescript +// Provide AGENT_LIFECYCLE on the current injector for downstream consumers +const parentInjector = inject(Injector); +const childInjector = Injector.create({ + providers: [{ provide: AGENT_LIFECYCLE, useValue: lifecycle }], + parent: parentInjector, +}); +// Store childInjector somewhere accessible ā€” match existing pattern +``` + +(The exact provider plumbing depends on agent's existing DI shape. Read agent.fn.ts carefully before this step. If `agent()` already exposes an `injector` on its return, provide AGENT_LIFECYCLE there. If not, use `runInInjectionContext` + the global injector and add a new internal injector pattern.) + +Now wire the signal updates into existing BehaviorSubject subscriptions. Find the stream-manager bridge subscription (`stream-manager.bridge.ts`) and inside `agent.fn.ts`: + +```typescript +// On first chunk of every stream: set streamStartedAt +status$.subscribe((status) => { + if (status === ResourceStatus.Loading && _streamStartedAt() === null) { + _streamStartedAt.set(Date.now()); + } +}); + +error$.subscribe((err) => { + if (err) { + const classification = err instanceof Error ? err.constructor.name : 'Unknown'; + _streamErrorAt.set({ at: Date.now(), classification }); + } +}); + +interrupt$.subscribe((int) => { + if (int && _interruptReceivedAt() === null) { + _interruptReceivedAt.set(Date.now()); + } +}); + +toolCalls$.subscribe((calls) => { + if (calls.length > 0 && _toolCallStartedAt() === null) { + _toolCallStartedAt.set(Date.now()); + } + const completed = calls.find((c) => c.result !== undefined); + if (completed && _toolCallCompletedAt() === null) { + _toolCallCompletedAt.set(Date.now()); + } +}); +``` + +In the `submit()` method, before the existing logic: + +```typescript +async submit(input: SubmitOptions<...>): Promise { + // ... existing input handling + if (input.interrupt !== undefined) { + _interruptResolvedAt.set(Date.now()); + } else if (input.messages && _threadCreatedAt() === null) { + _threadCreatedAt.set(Date.now()); + } + // ... existing submit +} +``` + +For `threadPersistedAt`, hook in the existing thread-restore code path (where the agent loads history from an existing threadId ā€” typically a `loadHistory()` or similar method): + +```typescript +async loadHistory(): Promise { + // ... existing load + _threadPersistedAt.set(Date.now()); +} +``` + +In `clearThread()`: + +```typescript +clearThread(): void { + // ... existing clear + _streamStartedAt.set(null); + _streamErrorAt.set(null); + _interruptReceivedAt.set(null); + _interruptResolvedAt.set(null); + _threadCreatedAt.set(null); + _threadPersistedAt.set(null); + _toolCallStartedAt.set(null); + _toolCallCompletedAt.set(null); +} +``` + +- [ ] **Step 4: Run, see pass** + +```bash +npx nx run langgraph:test -- --testPathPattern=lifecycle.spec +``` + +Expected: 10 tests passing. + +- [ ] **Step 5: Commit** + +```bash +git add libs/langgraph/src/lib/agent.fn.ts libs/langgraph/src/lib/lifecycle.spec.ts +git commit -m "$(cat <<'EOF' +feat(langgraph): wire AGENT_LIFECYCLE in agent.fn.ts + +Eight signal updates hooked into existing BehaviorSubject subscriptions +and the agent's submit/clearThread/loadHistory paths. Three new hooks +(interruptResolvedAt, threadCreatedAt, threadPersistedAt) ā€” five +signals derive from existing status$/error$/interrupt$/toolCalls$. +All reset on clearThread. + +10 tests cover all transitions. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +### Task 0.5: `@ngaf/render` RENDER_LIFECYCLE service + token + TDD + +**Files:** +- Create: `libs/render/src/lib/lifecycle.ts` +- Create: `libs/render/src/lib/render-lifecycle.service.ts` +- Create: `libs/render/src/lib/lifecycle.spec.ts` +- Modify: `libs/render/src/lib/provide-render.ts` +- Modify: `libs/render/src/public-api.ts` + +- [ ] **Step 1: Create the lifecycle interface + token** + +```typescript +// libs/render/src/lib/lifecycle.ts +import { InjectionToken, Signal } from '@angular/core'; + +export interface RenderLifecycle { + /** First mount event in this render context. Sticky ā€” does not reset. */ + readonly firstMountAt: Signal<{ kind: 'spec' | 'element'; elementType?: string; at: number } | null>; + /** Total mount count since render context started. */ + readonly mountCount: Signal; + /** Epoch ms of the most recent mount event. */ + readonly lastMountAt: Signal; + /** Epoch ms of the most recent state-change event. */ + readonly lastStateChangeAt: Signal; + /** Most recent handler invocation. */ + readonly lastHandlerInvokedAt: Signal<{ action: string; at: number } | null>; +} + +export const RENDER_LIFECYCLE = new InjectionToken('RENDER_LIFECYCLE'); +``` + +- [ ] **Step 2: Create the lifecycle service** + +```typescript +// libs/render/src/lib/render-lifecycle.service.ts +import { Injectable, signal, inject } from '@angular/core'; +import type { RenderLifecycle } from './lifecycle'; + +@Injectable({ providedIn: 'root' }) +export class RenderLifecycleService implements RenderLifecycle { + private _firstMountAt = signal<{ kind: 'spec' | 'element'; elementType?: string; at: number } | null>(null); + private _mountCount = signal(0); + private _lastMountAt = signal(null); + private _lastStateChangeAt = signal(null); + private _lastHandlerInvokedAt = signal<{ action: string; at: number } | null>(null); + + readonly firstMountAt = this._firstMountAt.asReadonly(); + readonly mountCount = this._mountCount.asReadonly(); + readonly lastMountAt = this._lastMountAt.asReadonly(); + readonly lastStateChangeAt = this._lastStateChangeAt.asReadonly(); + readonly lastHandlerInvokedAt = this._lastHandlerInvokedAt.asReadonly(); + + /** Called by render-spec.component.ts and render-element.component.ts on lifecycle events. */ + notifyLifecycle(event: { kind: 'spec' | 'element'; type: 'mounted' | 'destroyed'; elementType?: string }): void { + if (event.type === 'mounted') { + const now = Date.now(); + if (this._firstMountAt() === null) { + this._firstMountAt.set({ kind: event.kind, elementType: event.elementType, at: now }); + } + this._mountCount.update((c) => c + 1); + this._lastMountAt.set(now); + } + } + + notifyStateChange(): void { + this._lastStateChangeAt.set(Date.now()); + } + + notifyHandlerInvoked(action: string): void { + this._lastHandlerInvokedAt.set({ action, at: Date.now() }); + } +} +``` + +- [ ] **Step 3: Provide RENDER_LIFECYCLE via provide-render.ts** + +Open `libs/render/src/lib/provide-render.ts` and modify `provideRender()` to also provide the token: + +```typescript +import { RenderLifecycleService } from './render-lifecycle.service'; +import { RENDER_LIFECYCLE } from './lifecycle'; + +// Inside the providers array of provideRender(): +RenderLifecycleService, +{ provide: RENDER_LIFECYCLE, useExisting: RenderLifecycleService }, +``` + +- [ ] **Step 4: Wire the existing render-event stream into the service** + +Open `libs/render/src/lib/render-element.component.ts` (and `render-spec.component.ts`). Find the existing places where `RenderEvent`s are emitted. Inject the service and call `notifyLifecycle()`: + +```typescript +// Inside the component +private lifecycle = inject(RenderLifecycleService, { optional: true }); + +// On mount (existing hook) +this.lifecycle?.notifyLifecycle({ kind: 'element', type: 'mounted', elementType: this.elementType }); + +// On state change (where RenderStateChangeEvent fires) +this.lifecycle?.notifyStateChange(); + +// On handler invocation (where RenderHandlerEvent fires) +this.lifecycle?.notifyHandlerInvoked(action); +``` + +- [ ] **Step 5: Export from public-api.ts** + +```typescript +// libs/render/src/public-api.ts +export { RENDER_LIFECYCLE } from './lib/lifecycle'; +export type { RenderLifecycle } from './lib/lifecycle'; +``` + +- [ ] **Step 6: Write the failing test** + +Create `libs/render/src/lib/lifecycle.spec.ts`: + +```typescript +// @vitest-environment jsdom +import { describe, test, expect, beforeEach } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { RenderLifecycleService } from './render-lifecycle.service'; +import { RENDER_LIFECYCLE } from './lifecycle'; +import { provideRender } from './provide-render'; + +describe('RenderLifecycle', () => { + let service: RenderLifecycleService; + + beforeEach(() => { + TestBed.configureTestingModule({ + providers: [provideRender()], + }); + service = TestBed.inject(RENDER_LIFECYCLE) as RenderLifecycleService; + }); + + test('firstMountAt is null before any mount', () => { + expect(service.firstMountAt()).toBe(null); + }); + + test('firstMountAt captures the first mount and stays sticky', () => { + service.notifyLifecycle({ kind: 'element', type: 'mounted', elementType: 'button' }); + const first = service.firstMountAt(); + expect(first?.elementType).toBe('button'); + service.notifyLifecycle({ kind: 'element', type: 'mounted', elementType: 'card' }); + expect(service.firstMountAt()?.elementType).toBe('button'); + }); + + test('mountCount increments on each mount', () => { + service.notifyLifecycle({ kind: 'element', type: 'mounted' }); + service.notifyLifecycle({ kind: 'element', type: 'mounted' }); + service.notifyLifecycle({ kind: 'spec', type: 'mounted' }); + expect(service.mountCount()).toBe(3); + }); + + test('lastStateChangeAt updates on state change notifications', () => { + expect(service.lastStateChangeAt()).toBe(null); + service.notifyStateChange(); + expect(service.lastStateChangeAt()).toBeGreaterThan(0); + }); + + test('lastHandlerInvokedAt updates with action name and timestamp', () => { + service.notifyHandlerInvoked('save'); + expect(service.lastHandlerInvokedAt()?.action).toBe('save'); + }); +}); +``` + +- [ ] **Step 7: Run, see pass (or fail-then-pass)** + +```bash +npx nx run render:test -- --testPathPattern=lifecycle.spec +``` + +Expected: 5 tests passing. + +- [ ] **Step 8: Commit** + +```bash +git add libs/render/src/lib/lifecycle.ts libs/render/src/lib/render-lifecycle.service.ts libs/render/src/lib/lifecycle.spec.ts libs/render/src/lib/provide-render.ts libs/render/src/lib/render-element.component.ts libs/render/src/lib/render-spec.component.ts libs/render/src/public-api.ts +git commit -m "$(cat <<'EOF' +feat(render): add RENDER_LIFECYCLE token + service + wiring + +Service subscribes to the existing render-event stream and reduces to +five signals. firstMountAt is sticky; the rest update on each event. +Provided via provideRender() so all consumers automatically have access. + +5 tests cover all signal transitions. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +--- + +## Phase 1 ā€” `@ngaf/cockpit-telemetry` private library (~24 tests) + +### Task 1.1: Scaffold the Nx project + +**Files:** +- Create entire `libs/cockpit-telemetry/` directory tree + +- [ ] **Step 1: Create package.json** + +```json +// libs/cockpit-telemetry/package.json +{ + "name": "@ngaf/cockpit-telemetry", + "version": "0.0.0", + "license": "MIT", + "private": true, + "sideEffects": false, + "type": "module", + "peerDependencies": { + "@angular/core": "^20.0.0 || ^21.0.0" + }, + "dependencies": { + "posthog-js": "^1.373.0" + } +} +``` + +- [ ] **Step 2: Create project.json (mirroring other cockpit-* libs)** + +```jsonc +// libs/cockpit-telemetry/project.json +{ + "name": "cockpit-telemetry", + "$schema": "../../node_modules/nx/schemas/project-schema.json", + "sourceRoot": "libs/cockpit-telemetry/src", + "prefix": "lib", + "projectType": "library", + "tags": [], + "targets": { + "build": { + "executor": "@nx/angular:package", + "outputs": ["{workspaceRoot}/dist/libs/cockpit-telemetry"], + "options": { + "project": "libs/cockpit-telemetry/ng-package.json", + "tsConfig": "libs/cockpit-telemetry/tsconfig.lib.json" + } + }, + "test": { + "executor": "@nx/vitest:test", + "options": { "configFile": "libs/cockpit-telemetry/vite.config.mts" } + }, + "lint": { "executor": "@nx/eslint:lint" } + } +} +``` + +- [ ] **Step 3: Create the rest of the scaffolding files** + +Create these files with the standard content from `libs/chat/` and `libs/cockpit-shell/` as templates: +- `tsconfig.json` +- `tsconfig.lib.json` +- `tsconfig.spec.json` +- `ng-package.json` (entryFile `src/public-api.ts`) +- `eslint.config.mjs` +- `vite.config.mts` (matching `libs/chat/vite.config.mts` shape ā€” global jsdom env) +- `src/test-setup.ts` (matching `libs/chat/src/test-setup.ts`) +- `src/index.ts` ā†’ `export * from './public-api';` +- `src/public-api.ts` (empty for now; populated as files land) +- `README.md` (brief ā€” internal lib, "no app telemetry by default" framing, references libs/telemetry/README.md) + +- [ ] **Step 4: Add to tsconfig.base.json path alias** + +Open root `tsconfig.base.json`. Find the `compilerOptions.paths` block and add: + +```jsonc +"paths": { + // ... existing aliases + "@ngaf/cockpit-telemetry": ["libs/cockpit-telemetry/src/index.ts"] +} +``` + +- [ ] **Step 5: Verify Nx recognizes the project** + +```bash +npx nx show projects | grep -Fx cockpit-telemetry +``` + +Expected: prints `cockpit-telemetry`. + +- [ ] **Step 6: Commit** + +```bash +git add libs/cockpit-telemetry/ tsconfig.base.json +git commit -m "$(cat <<'EOF' +feat(cockpit-telemetry): scaffold private Nx library + +@ngaf/cockpit-telemetry ā€” private (not in publishable group), Angular +library, consumed by the 32 Angular examples via main.cockpit.ts +build-time entry override. Mirrors @ngaf/cockpit-shell/cockpit-ui +scaffold pattern. tsconfig.base.json path alias added. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +### Task 1.2: tokens.ts + events.ts + +- [ ] **Step 1: Create tokens.ts** + +```typescript +// libs/cockpit-telemetry/src/lib/tokens.ts +import { InjectionToken } from '@angular/core'; + +export interface CockpitTelemetryConfig { + /** PostHog project key. From URL param cockpit_phk. */ + posthogKey: string; + /** PostHog ingest host. From cockpit_host param or default. */ + posthogHost?: string; + /** Session-scoped distinct_id passed by the parent. */ + distinctId: string; + /** Capability slug (e.g. 'langgraph-streaming'). */ + capabilitySlug: string; + /** Sample rate. Default 1.0. */ + sampleRate?: number; +} + +export const COCKPIT_TELEMETRY_CONFIG = new InjectionToken( + 'COCKPIT_TELEMETRY_CONFIG', +); +``` + +- [ ] **Step 2: Create events.ts** + +```typescript +// libs/cockpit-telemetry/src/lib/events.ts +export type CockpitEventName = + | 'cockpit:recipe_opened' + | 'cockpit:mode_switched' + | 'cockpit:code_copied' + | 'cockpit:chat_first_message' + | 'cockpit:transport_connected' + | 'cockpit:thread_persisted' + | 'cockpit:interrupt_handled' + | 'cockpit:generative_component_rendered' + | 'cockpit:activation_complete'; +``` + +- [ ] **Step 3: Export from public-api.ts** + +```typescript +// libs/cockpit-telemetry/src/public-api.ts +export { COCKPIT_TELEMETRY_CONFIG } from './lib/tokens'; +export type { CockpitTelemetryConfig } from './lib/tokens'; +export type { CockpitEventName } from './lib/events'; +``` + +- [ ] **Step 4: Commit** + +```bash +git add libs/cockpit-telemetry/src/lib/tokens.ts libs/cockpit-telemetry/src/lib/events.ts libs/cockpit-telemetry/src/public-api.ts +git commit -m "feat(cockpit-telemetry): config token + typed event names + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 1.3: distinct-id.ts with TDD + +**Files:** +- Create: `libs/cockpit-telemetry/src/lib/distinct-id.ts` +- Create: `libs/cockpit-telemetry/src/lib/distinct-id.spec.ts` + +- [ ] **Step 1: Write the failing test** + +```typescript +// libs/cockpit-telemetry/src/lib/distinct-id.spec.ts +// @vitest-environment jsdom +import { describe, test, expect, beforeEach } from 'vitest'; +import { readCockpitConfigFromIframe } from './distinct-id'; + +describe('readCockpitConfigFromIframe', () => { + function setSearch(s: string): void { + Object.defineProperty(window, 'location', { + writable: true, + value: { ...window.location, search: s }, + }); + } + + beforeEach(() => setSearch('')); + + test('returns null when no URL params present', () => { + setSearch(''); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns null when cockpit_did is missing', () => { + setSearch('?cockpit_phk=k&cockpit_cap=c'); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns null when cockpit_phk is missing', () => { + setSearch('?cockpit_did=d&cockpit_cap=c'); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns null when cockpit_cap is missing', () => { + setSearch('?cockpit_did=d&cockpit_phk=k'); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns config with all params and default host', () => { + setSearch('?cockpit_did=session-1&cockpit_phk=phc_test&cockpit_cap=streaming'); + const config = readCockpitConfigFromIframe(); + expect(config).toEqual({ + distinctId: 'session-1', + posthogKey: 'phc_test', + capabilitySlug: 'streaming', + posthogHost: 'https://us.i.posthog.com', + }); + }); + + test('returns config with explicit host', () => { + setSearch('?cockpit_did=d&cockpit_phk=k&cockpit_cap=c&cockpit_host=https://eu.i.posthog.com'); + expect(readCockpitConfigFromIframe()?.posthogHost).toBe('https://eu.i.posthog.com'); + }); +}); +``` + +- [ ] **Step 2: Run, see fail** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=distinct-id.spec +``` + +Expected: Cannot find module './distinct-id'. + +- [ ] **Step 3: Implement distinct-id.ts** + +```typescript +// libs/cockpit-telemetry/src/lib/distinct-id.ts +import type { CockpitTelemetryConfig } from './tokens'; + +export function readCockpitConfigFromIframe(): CockpitTelemetryConfig | null { + if (typeof window === 'undefined') return null; + const params = new URLSearchParams(window.location.search); + const distinctId = params.get('cockpit_did'); + const posthogKey = params.get('cockpit_phk'); + const capabilitySlug = params.get('cockpit_cap'); + if (!distinctId || !posthogKey || !capabilitySlug) return null; + return { + posthogKey, + posthogHost: params.get('cockpit_host') ?? 'https://us.i.posthog.com', + distinctId, + capabilitySlug, + }; +} +``` + +- [ ] **Step 4: Run, see pass** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=distinct-id.spec +``` + +Expected: 6 tests passing. + +- [ ] **Step 5: Export + commit** + +Add to `libs/cockpit-telemetry/src/public-api.ts`: + +```typescript +export { readCockpitConfigFromIframe } from './lib/distinct-id'; +``` + +```bash +git add libs/cockpit-telemetry/src/lib/distinct-id.ts libs/cockpit-telemetry/src/lib/distinct-id.spec.ts libs/cockpit-telemetry/src/public-api.ts +git commit -m "feat(cockpit-telemetry): readCockpitConfigFromIframe ā€” URL param reader + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 1.4: activation-aggregator.ts with TDD + +- [ ] **Step 1: Write the failing test** + +```typescript +// libs/cockpit-telemetry/src/lib/activation-aggregator.spec.ts +// @vitest-environment jsdom +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { ActivationAggregator } from './activation-aggregator'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; + +vi.mock('posthog-js', () => ({ + default: { capture: vi.fn() }, +})); + +import posthog from 'posthog-js'; + +describe('ActivationAggregator', () => { + let aggregator: ActivationAggregator; + + beforeEach(() => { + vi.mocked(posthog.capture).mockClear(); + TestBed.configureTestingModule({ + providers: [ + { provide: COCKPIT_TELEMETRY_CONFIG, useValue: { + posthogKey: 'k', distinctId: 'd', capabilitySlug: 'streaming', + } }, + ActivationAggregator, + ], + }); + aggregator = TestBed.inject(ActivationAggregator); + }); + + test('does not fire activation_complete before all 5 signals', () => { + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('transport_connected'); + aggregator.markSignal('thread_persisted'); + expect(posthog.capture).not.toHaveBeenCalled(); + }); + + test('fires activation_complete exactly once when all 5 signals seen', () => { + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('transport_connected'); + aggregator.markSignal('thread_persisted'); + aggregator.markSignal('interrupt_handled'); + aggregator.markSignal('generative_component_rendered'); + expect(posthog.capture).toHaveBeenCalledTimes(1); + expect(posthog.capture).toHaveBeenCalledWith('cockpit:activation_complete', expect.any(Object)); + }); + + test('subsequent signals after complete do not re-fire', () => { + for (const sig of ['chat_first_message', 'transport_connected', 'thread_persisted', 'interrupt_handled', 'generative_component_rendered'] as const) { + aggregator.markSignal(sig); + } + aggregator.markSignal('chat_first_message'); + expect(posthog.capture).toHaveBeenCalledTimes(1); + }); + + test('duplicate signals are idempotent', () => { + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('transport_connected'); + aggregator.markSignal('transport_connected'); + expect(posthog.capture).not.toHaveBeenCalled(); + }); + + test('30-min window: stale first signal resets when newer one arrives outside window', () => { + const real = Date.now; + let now = 1_000_000; + Date.now = () => now; + try { + aggregator.markSignal('chat_first_message'); + now += 31 * 60 * 1000; // 31 min later + aggregator.markSignal('transport_connected'); + // The chat_first_message has expired; only transport_connected is in the current window + now += 1000; + aggregator.markSignal('thread_persisted'); + aggregator.markSignal('interrupt_handled'); + aggregator.markSignal('generative_component_rendered'); + // Need chat_first_message in this window too + expect(posthog.capture).not.toHaveBeenCalled(); + aggregator.markSignal('chat_first_message'); + expect(posthog.capture).toHaveBeenCalled(); + } finally { + Date.now = real; + } + }); + + test('emits duration_ms property when activation_complete fires', () => { + const real = Date.now; + let now = 5_000_000; + Date.now = () => now; + try { + aggregator.markSignal('chat_first_message'); + now += 1234; + aggregator.markSignal('transport_connected'); + aggregator.markSignal('thread_persisted'); + aggregator.markSignal('interrupt_handled'); + aggregator.markSignal('generative_component_rendered'); + const call = vi.mocked(posthog.capture).mock.calls[0]; + expect((call[1] as Record).duration_ms).toBe(1234); + expect((call[1] as Record).capability).toBe('streaming'); + } finally { + Date.now = real; + } + }); +}); +``` + +- [ ] **Step 2: Run, see fail** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=activation-aggregator.spec +``` + +- [ ] **Step 3: Implement** + +```typescript +// libs/cockpit-telemetry/src/lib/activation-aggregator.ts +import { Injectable, inject } from '@angular/core'; +import posthog from 'posthog-js'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; + +const WINDOW_MS = 30 * 60 * 1000; + +export type ActivationSignal = + | 'transport_connected' + | 'chat_first_message' + | 'thread_persisted' + | 'interrupt_handled' + | 'generative_component_rendered'; + +@Injectable() +export class ActivationAggregator { + private config = inject(COCKPIT_TELEMETRY_CONFIG); + private windowStartAt: number | null = null; + private seen = new Set(); + private complete = false; + + markSignal(signal: ActivationSignal): void { + if (this.complete) return; + const now = Date.now(); + // If first signal of window, anchor; if outside window, reset. + if (this.windowStartAt === null || (now - this.windowStartAt) > WINDOW_MS) { + this.windowStartAt = now; + this.seen.clear(); + } + this.seen.add(signal); + if (this.seen.size === 5) { + this.complete = true; + const durationMs = now - this.windowStartAt; + try { + posthog.capture('cockpit:activation_complete', { + capability: this.config.capabilitySlug, + duration_ms: durationMs, + }); + } catch { + // silent fail + } + } + } +} +``` + +- [ ] **Step 4: Run, see pass** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=activation-aggregator.spec +``` + +Expected: 6 tests passing. + +- [ ] **Step 5: Commit** + +```bash +git add libs/cockpit-telemetry/src/lib/activation-aggregator.ts libs/cockpit-telemetry/src/lib/activation-aggregator.spec.ts +git commit -m "feat(cockpit-telemetry): ActivationAggregator ā€” 5-signal rollup with 30-min window + +6 tests cover the rollup math: pre-complete state, fire-once-when-complete, +idempotent signals, 30-min window reset, duration_ms property on emit. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 1.5: cockpit-telemetry.service.ts with TDD + +- [ ] **Step 1: Write the failing test** + +```typescript +// libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.spec.ts +// @vitest-environment jsdom +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { signal } from '@angular/core'; +import { CockpitTelemetryService } from './cockpit-telemetry.service'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; +import { ActivationAggregator } from './activation-aggregator'; +import { CHAT_LIFECYCLE, type ChatLifecycle } from '@ngaf/chat'; +import { AGENT_LIFECYCLE, type AgentLifecycle } from '@ngaf/langgraph'; +import { RENDER_LIFECYCLE, type RenderLifecycle } from '@ngaf/render'; + +const mocks = vi.hoisted(() => ({ + init: vi.fn(), + capture: vi.fn(), +})); + +vi.mock('posthog-js', () => ({ + default: { init: mocks.init, capture: mocks.capture }, +})); + +function makeChatLifecycle(): ChatLifecycle & { _setFirstMessage: () => void } { + const firstMessageSent = signal(false); + return { + componentReady: signal(true).asReadonly(), + firstMessageSent: firstMessageSent.asReadonly(), + messageCount: signal(0).asReadonly(), + inputSubmittedAt: signal(null).asReadonly(), + _setFirstMessage: () => firstMessageSent.set(true), + }; +} + +describe('CockpitTelemetryService', () => { + let svc: CockpitTelemetryService; + let chat: ReturnType; + + beforeEach(() => { + mocks.init.mockClear(); + mocks.capture.mockClear(); + chat = makeChatLifecycle(); + TestBed.configureTestingModule({ + providers: [ + { provide: COCKPIT_TELEMETRY_CONFIG, useValue: { + posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming', + } }, + ActivationAggregator, + { provide: CHAT_LIFECYCLE, useValue: chat }, + CockpitTelemetryService, + ], + }); + svc = TestBed.inject(CockpitTelemetryService); + }); + + test('init() initializes posthog-js with memory persistence + bootstrap distinctID', () => { + svc.init(); + expect(mocks.init).toHaveBeenCalledWith('phc_test', expect.objectContaining({ + persistence: 'memory', + bootstrap: { distinctID: 'd1' }, + autocapture: false, + capture_pageview: false, + })); + }); + + test('init() is idempotent', () => { + svc.init(); + svc.init(); + expect(mocks.init).toHaveBeenCalledTimes(1); + }); + + test('fires cockpit:chat_first_message when ChatLifecycle.firstMessageSent flips to true', async () => { + svc.init(); + chat._setFirstMessage(); + await Promise.resolve(); + expect(mocks.capture).toHaveBeenCalledWith('cockpit:chat_first_message', expect.objectContaining({ + capability: 'streaming', + })); + }); + + test('does not fire if lifecycle was already-true at init time and never transitions', async () => { + chat._setFirstMessage(); // before init + svc.init(); + await Promise.resolve(); + // Effect runs once, captures the current state ā€” implementation detail to verify in code review + // For this test we accept fire-on-init is allowed; the contract is "fires once at most" + const calls = mocks.capture.mock.calls.filter(([e]) => e === 'cockpit:chat_first_message'); + expect(calls.length).toBeLessThanOrEqual(1); + }); + + test('no lifecycle present ā†’ no events fire', () => { + TestBed.resetTestingModule(); + TestBed.configureTestingModule({ + providers: [ + { provide: COCKPIT_TELEMETRY_CONFIG, useValue: { + posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming', + } }, + ActivationAggregator, + CockpitTelemetryService, + ], + }); + const svc2 = TestBed.inject(CockpitTelemetryService); + svc2.init(); + expect(mocks.capture).not.toHaveBeenCalled(); + }); + + test('captures include capability property from config', async () => { + svc.init(); + chat._setFirstMessage(); + await Promise.resolve(); + const call = mocks.capture.mock.calls.find(([e]) => e === 'cockpit:chat_first_message'); + expect((call?.[1] as Record).capability).toBe('streaming'); + }); +}); +``` + +(Skipping additional explicit tests for transport_connected, thread_persisted, interrupt_handled, generative_component_rendered ā€” they follow the same effect pattern. Their unit coverage comes from the spec's Ā§6.4 implementation + integration smoke in Phase 3.) + +- [ ] **Step 2: Run, see fail** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=cockpit-telemetry.service.spec +``` + +- [ ] **Step 3: Implement service** + +```typescript +// libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.ts +import { Injectable, inject, effect, Injector } from '@angular/core'; +import posthog from 'posthog-js'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; +import { ActivationAggregator } from './activation-aggregator'; +import { CHAT_LIFECYCLE } from '@ngaf/chat'; +import { AGENT_LIFECYCLE } from '@ngaf/langgraph'; +import { RENDER_LIFECYCLE } from '@ngaf/render'; +import type { CockpitEventName } from './events'; + +@Injectable() +export class CockpitTelemetryService { + private config = inject(COCKPIT_TELEMETRY_CONFIG); + private injector = inject(Injector); + private aggregator = inject(ActivationAggregator); + private initialized = false; + + init(): void { + if (this.initialized) return; + this.initialized = true; + + posthog.init(this.config.posthogKey, { + api_host: this.config.posthogHost ?? 'https://us.i.posthog.com', + persistence: 'memory', + bootstrap: { distinctID: this.config.distinctId }, + autocapture: false, + capture_pageview: false, + }); + + this.subscribeChat(); + this.subscribeAgent(); + this.subscribeRender(); + } + + private subscribeChat(): void { + const chat = this.injector.get(CHAT_LIFECYCLE, null, { optional: true }); + if (!chat) return; + let chatFired = false; + effect(() => { + if (chat.firstMessageSent() && !chatFired) { + chatFired = true; + this.capture('cockpit:chat_first_message'); + this.aggregator.markSignal('chat_first_message'); + } + }, { injector: this.injector }); + } + + private subscribeAgent(): void { + const agent = this.injector.get(AGENT_LIFECYCLE, null, { optional: true }); + if (!agent) return; + let transportFired = false, threadFired = false, interruptFired = false; + effect(() => { + if (agent.streamStartedAt() !== null && !transportFired) { + transportFired = true; + this.capture('cockpit:transport_connected'); + this.aggregator.markSignal('transport_connected'); + } + }, { injector: this.injector }); + effect(() => { + if (agent.threadPersistedAt() !== null && !threadFired) { + threadFired = true; + this.capture('cockpit:thread_persisted'); + this.aggregator.markSignal('thread_persisted'); + } + }, { injector: this.injector }); + effect(() => { + if (agent.interruptResolvedAt() !== null && !interruptFired) { + interruptFired = true; + this.capture('cockpit:interrupt_handled'); + this.aggregator.markSignal('interrupt_handled'); + } + }, { injector: this.injector }); + } + + private subscribeRender(): void { + const render = this.injector.get(RENDER_LIFECYCLE, null, { optional: true }); + if (!render) return; + let renderFired = false; + effect(() => { + if (render.firstMountAt() !== null && !renderFired) { + renderFired = true; + this.capture('cockpit:generative_component_rendered'); + this.aggregator.markSignal('generative_component_rendered'); + } + }, { injector: this.injector }); + } + + private capture(event: CockpitEventName, properties: Record = {}): void { + try { + posthog.capture(event, { ...properties, capability: this.config.capabilitySlug }); + } catch { + // silent fail + } + } +} +``` + +- [ ] **Step 4: Run, see pass** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=cockpit-telemetry.service.spec +``` + +Expected: 6 tests pass. + +- [ ] **Step 5: Commit** + +```bash +git add libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.ts libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.spec.ts +git commit -m "feat(cockpit-telemetry): CockpitTelemetryService ā€” lifecycle subscribers + posthog init + +Initializes posthog-js with memory persistence + parent-provided +distinct_id, subscribes to CHAT/AGENT/RENDER lifecycle tokens +(each optional ā€” graceful no-op if absent), fires cockpit:* events +and marks signals on the ActivationAggregator. + +6 tests cover init idempotency, capture format, missing-lifecycle +gracefulness, capability property stamping. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 1.6: provide-cockpit-telemetry.ts + +```typescript +// libs/cockpit-telemetry/src/lib/provide-cockpit-telemetry.ts +import { + makeEnvironmentProviders, + EnvironmentProviders, + ENVIRONMENT_INITIALIZER, + inject, +} from '@angular/core'; +import { COCKPIT_TELEMETRY_CONFIG, type CockpitTelemetryConfig } from './tokens'; +import { CockpitTelemetryService } from './cockpit-telemetry.service'; +import { ActivationAggregator } from './activation-aggregator'; + +export function provideCockpitTelemetry(config: CockpitTelemetryConfig): EnvironmentProviders { + return makeEnvironmentProviders([ + { provide: COCKPIT_TELEMETRY_CONFIG, useValue: config }, + ActivationAggregator, + CockpitTelemetryService, + { + provide: ENVIRONMENT_INITIALIZER, + multi: true, + useFactory: () => { + const svc = inject(CockpitTelemetryService); + return () => svc.init(); + }, + }, + ]); +} +``` + +- [ ] **Step 1: Create the file** with the content above. + +- [ ] **Step 2: Export from public-api.ts** + +```typescript +// add to libs/cockpit-telemetry/src/public-api.ts +export { provideCockpitTelemetry } from './lib/provide-cockpit-telemetry'; +``` + +- [ ] **Step 3: Commit** + +```bash +git add libs/cockpit-telemetry/src/lib/provide-cockpit-telemetry.ts libs/cockpit-telemetry/src/public-api.ts +git commit -m "feat(cockpit-telemetry): provideCockpitTelemetry() EnvironmentProviders factory + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 1.7: harness.ts with TDD + +- [ ] **Step 1: Write the failing test** + +```typescript +// libs/cockpit-telemetry/src/lib/harness.spec.ts +// @vitest-environment jsdom +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { bootstrapWithCockpitHarness } from './harness'; +import { Component, type ApplicationConfig } from '@angular/core'; + +const mocks = vi.hoisted(() => ({ + bootstrapApplication: vi.fn().mockResolvedValue(undefined), +})); + +vi.mock('@angular/platform-browser', () => ({ + bootstrapApplication: mocks.bootstrapApplication, +})); + +@Component({ selector: 'app-test', standalone: true, template: '' }) +class TestComponent {} + +describe('bootstrapWithCockpitHarness', () => { + function setSearch(s: string): void { + Object.defineProperty(window, 'location', { + writable: true, + value: { ...window.location, search: s }, + }); + } + + beforeEach(() => { + setSearch(''); + mocks.bootstrapApplication.mockClear(); + }); + + test('bootstraps pristine when no cockpit URL params present', async () => { + setSearch(''); + const appConfig: ApplicationConfig = { providers: [] }; + await bootstrapWithCockpitHarness(TestComponent, appConfig); + expect(mocks.bootstrapApplication).toHaveBeenCalledWith(TestComponent, appConfig); + }); + + test('bootstraps with provideCockpitTelemetry when params present', async () => { + setSearch('?cockpit_did=d1&cockpit_phk=phc_test&cockpit_cap=streaming'); + const appConfig: ApplicationConfig = { providers: [{ provide: 'TEST', useValue: 1 }] }; + await bootstrapWithCockpitHarness(TestComponent, appConfig); + const call = mocks.bootstrapApplication.mock.calls[0]; + expect(call[0]).toBe(TestComponent); + const cfg = call[1] as ApplicationConfig; + expect((cfg.providers ?? []).length).toBeGreaterThan(appConfig.providers!.length); + }); +}); +``` + +- [ ] **Step 2: Run, see fail** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=harness.spec +``` + +- [ ] **Step 3: Implement** + +```typescript +// libs/cockpit-telemetry/src/lib/harness.ts +import { bootstrapApplication } from '@angular/platform-browser'; +import { ApplicationConfig, Type } from '@angular/core'; +import { readCockpitConfigFromIframe } from './distinct-id'; +import { provideCockpitTelemetry } from './provide-cockpit-telemetry'; + +export async function bootstrapWithCockpitHarness( + component: Type, + appConfig: ApplicationConfig, +): Promise { + const harness = readCockpitConfigFromIframe(); + const providers = harness + ? [...(appConfig.providers ?? []), provideCockpitTelemetry(harness)] + : appConfig.providers ?? []; + await bootstrapApplication(component, { ...appConfig, providers }); +} +``` + +- [ ] **Step 4: Run, see pass + export** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=harness.spec +``` + +Expected: 2 tests pass. + +Add to `libs/cockpit-telemetry/src/public-api.ts`: +```typescript +export { bootstrapWithCockpitHarness } from './lib/harness'; +``` + +- [ ] **Step 5: Commit** + +```bash +git add libs/cockpit-telemetry/src/lib/harness.ts libs/cockpit-telemetry/src/lib/harness.spec.ts libs/cockpit-telemetry/src/public-api.ts +git commit -m "feat(cockpit-telemetry): bootstrapWithCockpitHarness ā€” main.cockpit.ts entry helper + +Each cockpit example's main.cockpit.ts calls this with its +AppComponent + appConfig. When URL params present, telemetry providers +are added; otherwise bootstraps pristine. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 1.8: Permanent browser silence test + +- [ ] **Step 1: Write the test** + +```typescript +// libs/cockpit-telemetry/src/lib/browser-silence.spec.ts +// @vitest-environment jsdom +import { describe, test, expect, vi } from 'vitest'; +import { readCockpitConfigFromIframe } from './distinct-id'; + +vi.mock('posthog-js', () => { + throw new Error('posthog-js MUST NOT be imported when no cockpit URL params are present'); +}); + +describe('browser silence (permanent contract)', () => { + test('no posthog-js import triggered by readCockpitConfigFromIframe when no URL params', () => { + // Should be safe ā€” just reads URL params + expect(readCockpitConfigFromIframe()).toBe(null); + // posthog-js mock has thrown by now if it was imported eagerly + }); +}); +``` + +- [ ] **Step 2: Run, expect pass** + +```bash +npx nx run cockpit-telemetry:test -- --testPathPattern=browser-silence.spec +``` + +- [ ] **Step 3: Commit** + +```bash +git add libs/cockpit-telemetry/src/lib/browser-silence.spec.ts +git commit -m "$(cat <<'EOF' +test(cockpit-telemetry): permanent browser silence contract test + +When the cockpit harness is not present (no URL params), no eager +import of posthog-js. Mirrors @ngaf/telemetry/browser silence pattern. +Stays green permanently. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +### Task 1.9: Run full library test suite + lint + +- [ ] **Step 1: Run all tests** + +```bash +npx nx run cockpit-telemetry:test +``` + +Expected: ~24 tests passing across 6 spec files. + +- [ ] **Step 2: Run lint** + +```bash +npx nx run cockpit-telemetry:lint +``` + +Expected: clean. + +- [ ] **Step 3: Run build** + +```bash +npx nx run cockpit-telemetry:build +``` + +Expected: builds successfully to `dist/libs/cockpit-telemetry`. + +No commit ā€” verification only. + +--- + +## Phase 2 ā€” React shell instrumentation (~17 tests) + +### Task 2.1: analytics module scaffold + +**Files:** +- Create: `apps/cockpit/src/lib/analytics/distinct-id.ts` + spec +- Create: `apps/cockpit/src/lib/analytics/properties.ts` + spec +- Create: `apps/cockpit/src/lib/analytics/events.ts` +- Create: `apps/cockpit/src/lib/analytics/client.ts` + spec + +- [ ] **Step 1: distinct-id.ts + test** + +```typescript +// apps/cockpit/src/lib/analytics/distinct-id.spec.ts +import { describe, test, expect, beforeEach } from 'vitest'; +import { getCockpitSessionId, _resetCockpitSessionIdForTesting } from './distinct-id'; + +describe('getCockpitSessionId', () => { + beforeEach(() => _resetCockpitSessionIdForTesting()); + + test('returns stable id within process', () => { + expect(getCockpitSessionId()).toBe(getCockpitSessionId()); + }); + + test('id has cockpit_ prefix + uuid shape', () => { + expect(getCockpitSessionId()).toMatch(/^cockpit_[0-9a-f-]{36}$/); + }); +}); +``` + +```typescript +// apps/cockpit/src/lib/analytics/distinct-id.ts +let cached: string | null = null; + +export function getCockpitSessionId(): string { + if (!cached) cached = `cockpit_${crypto.randomUUID()}`; + return cached; +} + +// @internal ā€” for tests only +export function _resetCockpitSessionIdForTesting(): void { + cached = null; +} +``` + +- [ ] **Step 2: properties.ts + test** + +```typescript +// apps/cockpit/src/lib/analytics/properties.spec.ts +import { describe, test, expect } from 'vitest'; +import { shouldCaptureAnalytics } from './properties'; + +describe('shouldCaptureAnalytics', () => { + test('returns false when no token', () => { + expect(shouldCaptureAnalytics({ token: undefined, captureLocal: true, host: 'cockpit.example.com', doNotTrack: false })).toBe(false); + }); + + test('returns false when DO_NOT_TRACK', () => { + expect(shouldCaptureAnalytics({ token: 'phc_x', captureLocal: true, host: 'cockpit.example.com', doNotTrack: true })).toBe(false); + }); + + test('returns false on localhost when captureLocal is false', () => { + expect(shouldCaptureAnalytics({ token: 'phc_x', captureLocal: false, host: 'localhost:4201', doNotTrack: false })).toBe(false); + }); + + test('returns true on localhost when captureLocal is true', () => { + expect(shouldCaptureAnalytics({ token: 'phc_x', captureLocal: true, host: 'localhost:4201', doNotTrack: false })).toBe(true); + }); + + test('returns true on production host', () => { + expect(shouldCaptureAnalytics({ token: 'phc_x', captureLocal: false, host: 'cockpit.example.com', doNotTrack: false })).toBe(true); + }); +}); +``` + +```typescript +// apps/cockpit/src/lib/analytics/properties.ts +export interface CaptureGuardInput { + token: string | undefined; + captureLocal: boolean; + host: string | undefined; + doNotTrack: boolean; +} + +export function shouldCaptureAnalytics(input: CaptureGuardInput): boolean { + if (!input.token) return false; + if (input.doNotTrack) return false; + if (!input.captureLocal && isLocalhost(input.host)) return false; + return true; +} + +function isLocalhost(host: string | undefined): boolean { + if (!host) return false; + return host === 'localhost' || host.startsWith('localhost:') || host.startsWith('127.0.0.1') || host.startsWith('0.0.0.0'); +} +``` + +- [ ] **Step 3: events.ts** + +```typescript +// apps/cockpit/src/lib/analytics/events.ts +export type CockpitShellEvent = + | 'cockpit:recipe_opened' + | 'cockpit:mode_switched' + | 'cockpit:code_copied'; + +export interface CockpitShellProps { + capability?: string; + category?: string; + from_capability?: string; + from_mode?: 'run' | 'code' | 'docs' | 'api'; + to_mode?: 'run' | 'code' | 'docs' | 'api'; + surface?: 'code_mode' | 'docs_code_snippet' | 'agentic_prompt'; + file_path?: string; +} +``` + +- [ ] **Step 4: client.ts + test** + +```typescript +// apps/cockpit/src/lib/analytics/client.spec.ts +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { track } from './client'; + +const mocks = vi.hoisted(() => ({ capture: vi.fn(), __loaded: true })); + +vi.mock('posthog-js', () => ({ + default: { + capture: mocks.capture, + get __loaded() { return mocks.__loaded; }, + }, +})); + +describe('track', () => { + beforeEach(() => { + mocks.capture.mockClear(); + mocks.__loaded = true; + }); + + test('fires posthog.capture when loaded', () => { + track('cockpit:recipe_opened', { capability: 'streaming' }); + expect(mocks.capture).toHaveBeenCalledWith('cockpit:recipe_opened', { capability: 'streaming' }); + }); + + test('no-ops when posthog not loaded', () => { + mocks.__loaded = false; + track('cockpit:mode_switched', { capability: 'x', from_mode: 'run', to_mode: 'code' }); + expect(mocks.capture).not.toHaveBeenCalled(); + }); + + test('passes empty properties when not provided', () => { + track('cockpit:code_copied'); + expect(mocks.capture).toHaveBeenCalledWith('cockpit:code_copied', {}); + }); +}); +``` + +```typescript +// apps/cockpit/src/lib/analytics/client.ts +import posthog from 'posthog-js'; +import type { CockpitShellEvent, CockpitShellProps } from './events'; + +export function track(event: CockpitShellEvent, props: CockpitShellProps = {}): void { + try { + if (typeof window !== 'undefined' && (posthog as any).__loaded) { + posthog.capture(event, props); + } + } catch { + // silent fail + } +} +``` + +- [ ] **Step 5: Run all analytics-module tests, see pass** + +```bash +npx nx run cockpit:test -- --testPathPattern="src/lib/analytics/" +``` + +Expected: ~10 tests passing across 3 spec files. + +- [ ] **Step 6: Commit** + +```bash +git add apps/cockpit/src/lib/analytics/ +git commit -m "$(cat <<'EOF' +feat(cockpit): analytics module ā€” distinct-id, properties, events, client + +Mirrors apps/website/src/lib/analytics/ structure. Memory-only session +UUID, shouldCaptureAnalytics guard with localhost gate + DO_NOT_TRACK +honoring, typed track() helper. ~10 tests. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +### Task 2.2: instrumentation-client.ts + +- [ ] **Step 1: Create the file** + +```typescript +// apps/cockpit/instrumentation-client.ts +import posthog from 'posthog-js'; +import { getCockpitSessionId } from './src/lib/analytics/distinct-id'; +import { shouldCaptureAnalytics } from './src/lib/analytics/properties'; + +const token = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN; +const captureLocal = process.env.NEXT_PUBLIC_COCKPIT_CAPTURE_LOCAL === 'true'; +const host = typeof window === 'undefined' ? undefined : window.location.host; +const doNotTrack = typeof navigator !== 'undefined' && navigator.doNotTrack === '1'; + +if (shouldCaptureAnalytics({ token, captureLocal, host, doNotTrack })) { + posthog.init(token!, { + api_host: process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_HOST ?? 'https://us.i.posthog.com', + persistence: 'memory', + bootstrap: { distinctID: getCockpitSessionId() }, + autocapture: false, + capture_pageview: false, + defaults: '2026-01-30', + }); +} +``` + +- [ ] **Step 2: Verify Next.js picks it up** + +```bash +nx run cockpit:build +``` + +Expected: build succeeds. (Next.js auto-detects `instrumentation-client.ts` in the app root.) + +- [ ] **Step 3: Add env vars to .env.example (root)** + +```bash +cat >> .env.example <<'EOF' + +# Cockpit shell analytics (apps/cockpit) +NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN= +NEXT_PUBLIC_COCKPIT_POSTHOG_HOST=https://us.i.posthog.com +NEXT_PUBLIC_COCKPIT_CAPTURE_LOCAL=false +EOF +``` + +- [ ] **Step 4: Commit** + +```bash +git add apps/cockpit/instrumentation-client.ts .env.example +git commit -m "feat(cockpit): posthog-js initialization via instrumentation-client.ts + +Memory persistence + parent-side session UUID. Off on localhost by +default (NEXT_PUBLIC_COCKPIT_CAPTURE_LOCAL=true to override). Honors +DO_NOT_TRACK. Three new env vars documented in .env.example. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 2.3: Sidebar instrumentation + +**Files:** +- Modify: `apps/cockpit/src/components/sidebar/sidebar.tsx` + +- [ ] **Step 1: Locate the capability click handler** + +Read `apps/cockpit/src/components/sidebar/sidebar.tsx`. Find where a sidebar item triggers navigation (likely a `Link` or `onClick`). + +- [ ] **Step 2: Add track() call** + +Import: + +```typescript +import { track } from '../../lib/analytics/client'; +``` + +In the click handler: + +```typescript +function handleCapabilityClick(capability: string, category: string, fromCapability?: string) { + track('cockpit:recipe_opened', { capability, category, from_capability: fromCapability }); + // ... existing navigation +} +``` + +- [ ] **Step 3: Add test to sidebar.spec.tsx** + +Open `apps/cockpit/src/components/sidebar/sidebar.spec.tsx` (or similar existing spec). Add: + +```typescript +import { describe, test, expect, vi } from 'vitest'; + +vi.mock('../../lib/analytics/client', () => ({ track: vi.fn() })); +import { track } from '../../lib/analytics/client'; + +test('fires cockpit:recipe_opened on capability click', async () => { + // Render the Sidebar with a known capability list, + // click a capability item, assert track was called + // (matching the existing test pattern in this file) +}); +``` + +- [ ] **Step 4: Run, see pass** + +```bash +npx nx run cockpit:test -- --testPathPattern=sidebar.spec +``` + +- [ ] **Step 5: Commit** + +```bash +git add apps/cockpit/src/components/sidebar/ +git commit -m "feat(cockpit): fire cockpit:recipe_opened on sidebar capability click + +Properties: capability, category, from_capability. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 2.4: Mode switcher instrumentation + +**Files:** +- Modify: `apps/cockpit/src/components/modes/mode-switcher.tsx` + +Same pattern as Task 2.3. Track `cockpit:mode_switched` with `{ capability, from_mode, to_mode }` on tab change. Test in `mode-switcher.spec.tsx`. + +- [ ] **Step 1-5:** As in Task 2.3. + +- [ ] **Step 6: Commit** + +```bash +git commit -m "feat(cockpit): fire cockpit:mode_switched on mode tab change + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 2.5: Code mode Copy instrumentation + +**Files:** +- Modify: `apps/cockpit/src/components/code-mode/code-mode.tsx` + +Same pattern. Fire `cockpit:code_copied` with `{ capability, surface: 'code_mode', file_path }` on Copy button click. + +- [ ] **Steps + commit** as in Task 2.3. + +### Task 2.6: Narrative docs Copy instrumentation + +**Files:** +- Modify: `apps/cockpit/src/components/narrative-docs/narrative-docs.tsx` + +Two Copy types: code snippets (`surface: 'docs_code_snippet'`) and agentic prompt (`surface: 'agentic_prompt'`). Fire `cockpit:code_copied` accordingly. + +- [ ] **Steps + commit** as in Task 2.3. + +### Task 2.7: RunMode iframe src + tests + +**Files:** +- Modify: `apps/cockpit/src/components/run-mode/run-mode.tsx` + +- [ ] **Step 1: Read the existing component** + +It currently renders ``. Add capability slug prop + URL param construction. + +- [ ] **Step 2: Implement** + +```typescript +import { getCockpitSessionId } from '../../lib/analytics/distinct-id'; + +interface RunModeProps { + entryTitle: string; + runtimeUrl: string | null; + capabilitySlug: string; // NEW +} + +function buildIframeSrc(runtimeUrl: string, capabilitySlug: string): string { + const url = new URL(runtimeUrl); + url.searchParams.set('cockpit_did', getCockpitSessionId()); + url.searchParams.set('cockpit_cap', capabilitySlug); + const phk = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN; + if (phk) url.searchParams.set('cockpit_phk', phk); + const host = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_HOST; + if (host) url.searchParams.set('cockpit_host', host); + return url.toString(); +} + +export function RunMode({ entryTitle, runtimeUrl, capabilitySlug }: RunModeProps) { + if (!runtimeUrl) { + return
; + } + return ( +
+ +
+ ); +} +``` + +- [ ] **Step 3: Update callers** + +Find anywhere `` is rendered (likely `[...slug]/page.tsx`). Pass the capability slug. + +- [ ] **Step 4: Add test** + +In `run-mode.spec.tsx` (create or extend): + +```typescript +import { describe, test, expect, vi } from 'vitest'; +import { render } from '@testing-library/react'; +import { RunMode } from './run-mode'; + +vi.mock('../../lib/analytics/distinct-id', () => ({ + getCockpitSessionId: () => 'cockpit_test-uuid', +})); + +test('iframe src includes cockpit_did and cockpit_cap query params', () => { + const { container } = render( + , + ); + const iframe = container.querySelector('iframe')!; + const src = new URL(iframe.src); + expect(src.searchParams.get('cockpit_did')).toBe('cockpit_test-uuid'); + expect(src.searchParams.get('cockpit_cap')).toBe('streaming'); +}); +``` + +- [ ] **Step 5: Run, see pass** + +```bash +npx nx run cockpit:test -- --testPathPattern=run-mode.spec +``` + +- [ ] **Step 6: Commit** + +```bash +git add apps/cockpit/src/components/run-mode/ apps/cockpit/src/app +git commit -m "$(cat <<'EOF' +feat(cockpit): RunMode appends cockpit_did/cockpit_cap to iframe src + +The iframe URL now carries the session UUID + capability slug + posthog +key + host so the Angular harness can correlate to the parent session. + +Co-Authored-By: Claude Opus 4.7 +EOF +)" +``` + +--- + +## Phase 3 ā€” Canonical streaming example + smoke test + +### Task 3.1: main.cockpit.ts for streaming + +- [ ] **Step 1: Create main.cockpit.ts** + +```typescript +// cockpit/langgraph/streaming/angular/src/main.cockpit.ts +import { StreamingComponent } from './app/streaming.component'; +import { appConfig } from './app/app.config'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(StreamingComponent, appConfig); +``` + +- [ ] **Step 2: Verify import resolves via tsconfig path alias** + +```bash +cd cockpit/langgraph/streaming/angular && npx tsc --noEmit && cd - +``` + +Expected: clean. + +- [ ] **Step 3: Commit** + +```bash +git add cockpit/langgraph/streaming/angular/src/main.cockpit.ts +git commit -m "feat(cockpit-streaming): main.cockpit.ts harness entry + +Three-line harness uses bootstrapWithCockpitHarness from +@ngaf/cockpit-telemetry. Pristine main.ts unchanged. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 3.2: Add cockpit build configuration to project.json + +- [ ] **Step 1: Modify project.json** + +Open `cockpit/langgraph/streaming/angular/project.json`. Find the `build` target. Add a `cockpit` configuration: + +```jsonc +"build": { + "executor": "@angular/build:application", + "configurations": { + "production": { /* existing ā€” keep */ }, + "cockpit": { + "browser": "src/main.cockpit.ts", + // ... mirror production settings except for the browser entry + } + } +} +``` + +Similarly add to `serve`: + +```jsonc +"serve": { + "configurations": { + "production": { "buildTarget": ":build:production" }, + "cockpit": { "buildTarget": ":build:cockpit" } + } +} +``` + +- [ ] **Step 2: Verify Nx config** + +```bash +npx nx show project langgraph-streaming-angular --json | grep -A 5 cockpit +``` + +Expected: cockpit configuration appears. + +- [ ] **Step 3: Update apps/cockpit/project.json serve-streaming to use the cockpit config** + +```jsonc +"serve-streaming": { + "executor": "@nx/devkit:run-commands", + "options": { + "command": "nx run langgraph-streaming-angular:serve:cockpit" + } +} +``` + +- [ ] **Step 4: Verify the cockpit serve target builds** + +```bash +npx nx run langgraph-streaming-angular:build:cockpit +``` + +Expected: builds successfully. + +- [ ] **Step 5: Commit** + +```bash +git add cockpit/langgraph/streaming/angular/project.json apps/cockpit/project.json +git commit -m "feat(cockpit-streaming): add cockpit build configuration + +cockpit/<...>/project.json gains a cockpit build that uses main.cockpit.ts +as the entry. apps/cockpit:serve-streaming now invokes +serve:cockpit on the example. Production build unchanged. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 3.3: Local Chrome MCP smoke test + +This is verification, not implementation. The subagent or operator runs through the smoke test and records findings. + +- [ ] **Step 1: Start cockpit shell** + +```bash +nx run cockpit:serve +``` + +- [ ] **Step 2: Start streaming example via cockpit config** + +In a second terminal: +```bash +nx run cockpit:serve-streaming +``` + +- [ ] **Step 3: Chrome MCP ā€” navigate to cockpit and verify** + +Use Chrome MCP: +1. Open http://localhost:4201 +2. Verify cockpit shell loads +3. Click "LangGraph / Streaming" in sidebar +4. Verify `cockpit:recipe_opened` fires (inspect Network for posthog requests or use `read_console_messages` to confirm) +5. Verify iframe src contains `?cockpit_did=cockpit_&cockpit_cap=langgraph-streaming&cockpit_phk=` +6. Type a message in chat, hit send +7. Verify in PostHog Live Events (manual): `cockpit:chat_first_message` + `cockpit:transport_connected` arrive with the same distinct_id as the parent's `cockpit:recipe_opened` +8. If a thread persists, reload ā€” verify `cockpit:thread_persisted` fires +9. If generative components render ā€” verify `cockpit:generative_component_rendered` + +- [ ] **Step 4: Record findings** + +Capture the smoke test results in the PR body (no commit needed; this is verification documentation). + +- [ ] **Step 5: Smoke complete** + +If all events fire with matching distinct_id, Phase 3 succeeds. If anything fails, fix and re-run. + +No commit for this task ā€” verification only. + +--- + +## Phase 4 ā€” Roll out remaining 31 examples (batched per category) + +Each batch follows an identical pattern. Per-example uniform template: + +```typescript +// cockpit///angular/src/main.cockpit.ts +import { } from './app/.component'; +import { appConfig } from './app/app.config'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(, appConfig); +``` + +Plus per-example `project.json` cockpit build configuration (same as Task 3.2). +Plus `apps/cockpit/project.json` updates to point `serve-` targets at the cockpit config. + +Per batch: write main.cockpit.ts files, update project.jsons, smoke test the capability via Chrome MCP, commit. + +### Task 4.1: LangGraph batch (7 remaining examples) + +Examples to wire: +- `cockpit/langgraph/persistence/angular` +- `cockpit/langgraph/durable-execution/angular` +- `cockpit/langgraph/interrupts/angular` +- `cockpit/langgraph/memory/angular` +- `cockpit/langgraph/subgraphs/angular` +- `cockpit/langgraph/time-travel/angular` +- `cockpit/langgraph/deployment-runtime/angular` + +- [ ] **Step 1: Write all 7 main.cockpit.ts files** (template applied per example; component import differs) +- [ ] **Step 2: Update all 7 project.json files** (add cockpit build configuration) +- [ ] **Step 3: Update apps/cockpit/project.json** serve-* targets for these 7 capabilities to use cockpit config +- [ ] **Step 4: Smoke test each capability via Chrome MCP** ā€” verify events fire for each +- [ ] **Step 5: Commit as one batch** + +```bash +git add cockpit/langgraph/*/angular/src/main.cockpit.ts cockpit/langgraph/*/angular/project.json apps/cockpit/project.json +git commit -m "feat(cockpit-langgraph): wire 7 examples with cockpit-telemetry harness + +Each example's main.cockpit.ts is a 3-line bootstrap; project.json +gains a cockpit build configuration. Pristine main.ts unchanged. + +Smoke tested each capability via Chrome MCP ā€” events fire with +correct capability slug + matching distinct_id with parent. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 4.2: Deep Agents batch (6 examples) + +Examples: planning, filesystem, subagents, memory, skills, sandboxes. + +- [ ] **Step 1-5:** As in Task 4.1. + +### Task 4.3: Chat batch (5 examples) + +Examples: messages, input, interrupts, tool-calls, subagents. + +- [ ] **Step 1-5:** As in Task 4.1. + +### Task 4.4: Render + others batch (remaining ~13 examples) + +Includes Render examples + any AG-UI / A2UI / other Angular examples found via: + +```bash +find ./cockpit -type d -name angular | grep -vE "(langgraph|deep-agents|chat)/.*/angular$" +``` + +- [ ] **Step 1-5:** As in Task 4.1. + +After Phase 4 completes, all 32 examples have `main.cockpit.ts` + cockpit build configurations. Activation funnel populates from every cockpit capability. + +--- + +## Phase 5 ā€” Website docs for the three `*_LIFECYCLE` tokens + +### Task 5.1: chat/lifecycle.md docs page + +**Files:** +- Create: `apps/website/src/content/docs/chat/lifecycle.md` + +- [ ] **Step 1: Write the docs page** + +```markdown +--- +title: Chat Lifecycle Signals +description: Subscribe to per-instance lifecycle signals from +--- + +# Chat Lifecycle Signals + +The `@ngaf/chat` library exposes per-instance lifecycle signals via the `CHAT_LIFECYCLE` injection token. Consumers can subscribe to these signals for debugging, custom dashboards, or telemetry integrations. + +## Interface + +\`\`\`typescript +import { InjectionToken, Signal } from '@angular/core'; + +export interface ChatLifecycle { + /** True after initializes with a non-null agent binding. */ + readonly componentReady: Signal; + /** True after the first user submit. Sticky for the life of the chat instance. */ + readonly firstMessageSent: Signal; + /** Count of user submits. Resets on clearThread. */ + readonly messageCount: Signal; + /** Epoch ms of the most recent user submit. Resets on clearThread. */ + readonly inputSubmittedAt: Signal; +} + +export const CHAT_LIFECYCLE = new InjectionToken('CHAT_LIFECYCLE'); +\`\`\` + +## Subscribing + +\`\`\`typescript +import { Component, inject, effect } from '@angular/core'; +import { CHAT_LIFECYCLE } from '@ngaf/chat'; + +@Component(...) +export class MyComponent { + private lifecycle = inject(CHAT_LIFECYCLE); + + constructor() { + effect(() => { + if (this.lifecycle.firstMessageSent()) { + console.log('User sent their first message at', this.lifecycle.inputSubmittedAt()); + } + }); + } +} +\`\`\` + +## Reset semantics + +| Signal | Resets on `clearThread()`? | +|--------|----------------------------| +| `componentReady` | no | +| `firstMessageSent` | **no (sticky for life of \`\`)** | +| `messageCount` | yes (to 0) | +| `inputSubmittedAt` | yes (to null) | + +## Privacy + +These signals contain no message content, no user input, no PII. They are timestamps and counts only. The trust contract at [libs/telemetry/README.md](https://github.com/cacheplane/angular-agent-framework/blob/main/libs/telemetry/README.md) applies: **no app telemetry by default.** Subscribing to CHAT_LIFECYCLE in your code does not fire any telemetry; what you do with the signal values is your choice. +``` + +- [ ] **Step 2: Commit** + +```bash +git add apps/website/src/content/docs/chat/lifecycle.md +git commit -m "docs(website): chat/lifecycle.md ā€” CHAT_LIFECYCLE signal docs + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 5.2: langgraph/lifecycle.md docs page + +Same shape as Task 5.1, for `AGENT_LIFECYCLE` (8 signals). Notes the three new hook points + five derived signals. + +- [ ] **Step 1: Write the page** (mirror Task 5.1's structure) +- [ ] **Step 2: Commit** + +### Task 5.3: render/lifecycle.md docs page + +Same shape, for `RENDER_LIFECYCLE` (5 signals). Notes that all derive from the existing `RenderEvent` stream. + +- [ ] **Step 1: Write the page** +- [ ] **Step 2: Commit** + +### Task 5.4: Link from each lib's landing page + +- [ ] **Step 1: Modify chat landing** + +Open `apps/website/src/content/docs/chat/getting-started/introduction.md` (or the docs index for chat). Add a link to `/docs/chat/lifecycle`. + +- [ ] **Step 2: Modify langgraph landing** + +Same for langgraph docs index. + +- [ ] **Step 3: Modify render landing** + +Same for render docs index. + +- [ ] **Step 4: Commit** + +```bash +git add apps/website/src/content/docs/{chat,langgraph,render}/ +git commit -m "docs(website): link lifecycle pages from each lib's landing + +Co-Authored-By: Claude Opus 4.7 " +``` + +--- + +## Phase 6 ā€” Taxonomy + dashboard cleanup + +### Task 6.1: Update docs/gtm/taxonomy.md + +**Files:** +- Modify: `docs/gtm/taxonomy.md` + +- [ ] **Step 1: Locate the cockpit events table** and: + - Remove the `cockpit:install_command_copied` row + - Rename `cockpit:six_signals_complete` ā†’ `cockpit:activation_complete` + - Add a brief note: "Activation funnel is 5 signals as of Spec 1C. `ngaf:postinstall` is a separate top-of-funnel chart ā€” uncorrelated to cockpit sessions by design." + +- [ ] **Step 2: Update the version + change log** + +Append a row to the version table at the bottom: + +```markdown +| 2026-05-15 | Drop cockpit:install_command_copied, rename cockpit:six_signals_complete ā†’ cockpit:activation_complete (Spec 1C). | +``` + +- [ ] **Step 3: Commit** + +```bash +git add docs/gtm/taxonomy.md +git commit -m "chore(gtm): drop install_command_copied + rename activation event + +Activation funnel is 5 signals per Spec 1C. ngaf:postinstall is its +own top-of-funnel metric, uncorrelated to cockpit sessions. + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 6.2: Rename + update activation funnel insight + +**Files:** +- Rename: `tools/posthog/insights/six-signal-activation-funnel.json` ā†’ `tools/posthog/insights/activation-funnel.json` +- Modify: the renamed file's content (5 steps) + +- [ ] **Step 1: Rename** + +```bash +git mv tools/posthog/insights/six-signal-activation-funnel.json tools/posthog/insights/activation-funnel.json +``` + +- [ ] **Step 2: Update slug + steps** + +```jsonc +// tools/posthog/insights/activation-funnel.json +{ + "slug": "activation-funnel", // RENAMED from "six-signal-activation-funnel" + "posthog_id": null, // null ā†’ forces recreate on next apply (insight gets a new id) + "kind": "funnel", + "name": "Activation funnel (30-min window)", + "window_minutes": 30, + "steps": [ + { "event": "cockpit:chat_first_message" }, + { "event": "cockpit:transport_connected" }, + { "event": "cockpit:thread_persisted" }, + { "event": "cockpit:interrupt_handled" }, + { "event": "cockpit:generative_component_rendered" } + ], + "date_from": "-30d" +} +``` + +- [ ] **Step 3: Commit** + +```bash +git add tools/posthog/insights/ +git commit -m "chore(posthog): rename six-signal-activation-funnel ā†’ activation-funnel + +5 steps (dropped install_command_copied), 30-minute window. posthog_id +nulled to force create on next sync (PostHog will assign a new id). + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 6.3: Update developer-funnel dashboard + +**Files:** +- Modify: `tools/posthog/dashboards/developer-funnel.json` + +- [ ] **Step 1: Update insight reference** + +Find the tile referencing `six-signal-activation-funnel` and rename: + +```jsonc +{ "insight": "activation-funnel" } // was: { "insight": "six-signal-activation-funnel" } +``` + +- [ ] **Step 2: Commit** + +```bash +git add tools/posthog/dashboards/developer-funnel.json +git commit -m "chore(posthog): developer-funnel references activation-funnel insight + +Co-Authored-By: Claude Opus 4.7 " +``` + +### Task 6.4: posthog:sync plan + apply + +- [ ] **Step 1: Plan** + +```bash +export POSTHOG_PERSONAL_API_KEY= +export POSTHOG_PROJECT_ID= +npx nx run posthog-tools:sync:plan +``` + +Expected output: shows `[create]` for `activation-funnel`, `[orphan]` for the old `six-signal-activation-funnel` insight (orphan because the rename = local slug changed; PostHog's id-by-name match fails since the new slug doesn't match remote name either). + +- [ ] **Step 2: Decision ā€” orphan handling** + +The old insight in PostHog still exists with its content unchanged. Two options: +- (a) Run `--apply --delete-orphans` to remove the old insight. +- (b) Run `--apply` without `--delete-orphans`; old insight stays in PostHog as orphan (manual cleanup later via the PostHog UI). + +Recommend (b) for safety ā€” don't delete in the same commit as the rename. + +- [ ] **Step 3: Apply** + +```bash +npx nx run posthog-tools:sync:apply +``` + +Expected: creates the new `activation-funnel` insight + the existing `developer-funnel` dashboard gets PATCHed to reference the new insight. Old insight stays as orphan. + +- [ ] **Step 4: Verify in PostHog UI via Chrome MCP** + +Navigate to `https://us.posthog.com/project//dashboard/` and confirm: +- "Activation funnel (30-min window)" is the new tile name +- 5 steps shown +- Old "Six-signal activation (30-min window)" insight still exists as a separate (orphaned) insight + +- [ ] **Step 5: Commit the posthog_id writeback** + +The apply step writes back the new insight's `posthog_id` into `tools/posthog/insights/activation-funnel.json`. Commit: + +```bash +git add tools/posthog/insights/activation-funnel.json +git commit -m "chore(posthog): writeback posthog_id for renamed activation-funnel insight + +Co-Authored-By: Claude Opus 4.7 " +``` + +--- + +## Self-Review + +**1. Spec coverage:** + +| Spec Ā§ | Covered by | +|--------|-----------| +| Ā§3 Scope (in: 3 lifecycle tokens) | Phase 0 Tasks 0.1-0.5 | +| Ā§3 Scope (in: @ngaf/cockpit-telemetry private lib) | Phase 1 Tasks 1.1-1.9 | +| Ā§3 Scope (in: React shell instrumentation) | Phase 2 Tasks 2.1-2.7 | +| Ā§3 Scope (in: cross-frame correlation) | Phase 2 Task 2.7 + Phase 1 Task 1.3 + Task 3.2 | +| Ā§3 Scope (in: memory-only persistence) | Phase 2 Task 2.2 + Phase 1 Task 1.5 | +| Ā§3 Scope (in: main.cockpit.ts per example) | Phase 3 Task 3.1 + Phase 4 Tasks 4.1-4.4 | +| Ā§3 Scope (in: canonical streaming example wired) | Phase 3 Tasks 3.1-3.3 | +| Ā§3 Scope (in: 32 examples rolled out in batches) | Phase 3 + Phase 4 | +| Ā§3 Scope (in: taxonomy + dashboard updates) | Phase 6 Tasks 6.1-6.4 | +| Ā§3 Scope (in: per-example smoke tests) | Phase 3 Task 3.3 + Phase 4 (smoke per batch) | +| Ā§3 Scope (in: website docs for lifecycle tokens) | Phase 5 Tasks 5.1-5.4 | +| Ā§5 Library lifecycle additions | Phase 0 (CHAT 0.1-0.2, AGENT 0.3-0.4, RENDER 0.5) | +| Ā§6 cockpit-telemetry internals | Phase 1 (tokens 1.2, distinct-id 1.3, aggregator 1.4, service 1.5, provider 1.6, harness 1.7, silence 1.8) | +| Ā§7 React shell instrumentation | Phase 2 (analytics module 2.1, instrumentation-client 2.2, components 2.3-2.6, run-mode 2.7) | +| Ā§8 main.cockpit.ts build override | Phase 3 (canonical) + Phase 4 (rest) | +| Ā§9 Cross-frame correlation | Phase 2 Task 2.7 (iframe src) + Phase 1 Task 1.3 (read on iframe side) | +| Ā§10 Testing strategy | Each Phase 0-2 task uses TDD; Phase 1.8 permanent silence test; Phase 3 + Phase 4 smoke tests | +| Ā§11 Phases | All 6 phases mapped 1:1 in this plan | +| Ā§12 Risks | Mitigations baked into tasks (optional injection in 1.5, smoke tests for 1c-2.7 verification, etc.) | +| Ā§13 Deliverables | All checkboxes covered | + +**2. Placeholder scan:** No "TBD", "fill in details", "similar to Task N" without repeating. āœ“ + +**3. Type consistency:** +- `ChatLifecycle` interface (Task 0.1) ā†” wiring (Task 0.2) ā†” service injection (Task 1.5) ā€” same shape +- `AgentLifecycle` interface (Task 0.3) ā†” agent.fn.ts wiring (Task 0.4) ā†” service injection (Task 1.5) ā€” same shape (8 signals) +- `RenderLifecycle` interface (Task 0.5) ā†” service ā†” subscriber (Task 1.5) ā€” same shape (5 signals) +- `CockpitTelemetryConfig` (Task 1.2 tokens.ts) ā†” readCockpitConfigFromIframe (Task 1.3) ā†” service constructor (Task 1.5) ā†” harness (Task 1.7) ā€” same shape +- `CockpitEventName` (Task 1.2 events.ts) used in service (Task 1.5) and React shell client (Task 2.1) ā€” same union; React shell uses subset (CockpitShellEvent in Task 2.1's events.ts) which is correct +- `ActivationSignal` (Task 1.4) ā€” 5 values, matches the 5 service subscribers in Task 1.5 +- Method names: `markSignal()` (Task 1.4) used by service (Task 1.5) āœ“; `init()` (Task 1.5) called by provider (Task 1.6) āœ“; `bootstrapWithCockpitHarness()` (Task 1.7) called by example main.cockpit.ts (Task 3.1 + Phase 4) āœ“ +- Env var names: `NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN` consistent across Task 2.2 + Task 2.7 + .env.example āœ“ +- URL param names: `cockpit_did`, `cockpit_phk`, `cockpit_cap`, `cockpit_host` consistent across Task 1.3 (read) + Task 2.7 (write) āœ“ diff --git a/docs/superpowers/specs/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation-design.md b/docs/superpowers/specs/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation-design.md new file mode 100644 index 000000000..91598afee --- /dev/null +++ b/docs/superpowers/specs/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation-design.md @@ -0,0 +1,718 @@ +--- +workstream: analytics-foundation-1c-cockpit-instrumentation +status: approved +owner: brian +phase: 0 +spec: docs/superpowers/specs/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation-design.md +plan: docs/superpowers/plans/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation.md +parent: docs/superpowers/specs/gtm/2026-05-13-gtm-meta-design.md +--- + +# Analytics Foundation 1C ā€” Cockpit Instrumentation (Design) + +> Spec 1C of the Cacheplane GTM motion. Instruments cockpit's three surfaces ā€” the React/Next.js shell, the 32 Angular example apps loaded in iframes, and the cross-frame correlation that ties them into one session ā€” so the developer-funnel dashboard from Spec 1A populates with real cohort data. + +## 1. Goal + +Wire the activation funnel events for cockpit visitors: +- **Outer (React shell)**: `cockpit:recipe_opened`, `cockpit:mode_switched`, `cockpit:code_copied` +- **Inner (Angular iframe, per example)**: `cockpit:chat_first_message`, `cockpit:transport_connected`, `cockpit:thread_persisted`, `cockpit:interrupt_handled`, `cockpit:generative_component_rendered` +- **Rollup**: `cockpit:activation_complete` when all five inner signals fire within 30 minutes (per-session) + +End state: a cockpit visitor evaluating the framework sends one correlated stream of events; PostHog's `activation-funnel` insight reflects real cohort data. Reference example code (what external developers read) stays pristine. + +## 2. Context + +- Parent: `docs/superpowers/specs/gtm/2026-05-13-gtm-meta-design.md` Ā§7 (analytics architecture). +- Spec 1A (`tools/posthog/`) shipped the dashboards-as-code pipeline + `developer-funnel` dashboard. The activation-funnel insight currently has no real data. +- Spec 1B (`@ngaf/telemetry`) shipped the public telemetry library + trust contract. +- PR #328 (`ba4904f2 feat(telemetry): capture installs from published packages`, on main as of 2026-05-15) made important changes that Spec 1C inherits: + - `@ngaf/telemetry` no longer bundles `posthog-node`; uses `fetch()` against `apps/website/src/app/api/ingest/route.ts` proxy + - Every publishable `@ngaf/*` package now fires `ngaf:postinstall` on install + - `ngaf:postinstall` is anonymous (per-process), package-side, NOT correlatable to cockpit sessions ā†’ install signal is a separate top-of-funnel metric, NOT an activation step + - Trust contract copy unified to "no app telemetry by default" / "package installs send a minimal opt-out ping" +- **Cockpit is internal product**, not a customer-facing library. Different telemetry posture than `@ngaf/*` libs: on by default in production, off on localhost unless explicitly enabled. +- **Example apps are reference code**: external developers read them as the canonical pattern for consuming `@ngaf/chat`, `@ngaf/langgraph`, `@ngaf/render`. Telemetry wiring MUST NOT appear in `main.ts`, `app.config.ts`, or any component the Code mode tab surfaces. + +## 3. Scope + +**In scope:** + +- Three new public `*_LIFECYCLE` `InjectionToken`s in `@ngaf/chat`, `@ngaf/langgraph`, `@ngaf/render` exposing per-instance lifecycle signals. Additive public API; joins the publishable fixed-version group. +- New **private** library `@ngaf/cockpit-telemetry` at `libs/cockpit-telemetry/` (private convention matching existing `@ngaf/cockpit-shell`, `@ngaf/cockpit-ui`, etc. ā€” `"private": true`, not in publishable group, aliased via tsconfig path). +- React shell (`apps/cockpit`) instrumentation: own analytics module mirroring `apps/website/src/lib/analytics/`, uses `posthog-js` directly, fires shell-side events. +- Cross-frame correlation: session UUID generated parent-side, passed to iframe via URL query params. +- Memory-only persistence on BOTH frames ā€” no localStorage, no cookies. Refresh = new session. +- `main.cockpit.ts` build-time entry override per example. Reference source (`main.ts`, `app.config.ts`, components) stays pristine. Each example's `project.json` gains a `cockpit` build configuration. +- One canonical example wired and verified end-to-end: `cockpit/langgraph/streaming/angular/`. +- All 32 examples rolled out in batched per-category commits within this spec's plan. +- Taxonomy + dashboard updates: drop `cockpit:install_command_copied`, rename `cockpit:six_signals_complete` ā†’ `cockpit:activation_complete`, rename insight `six-signal-activation-funnel.json` ā†’ `activation-funnel.json`, update funnel to 5 steps. +- Per-example smoke test (Chrome MCP) verifying events fire with correct distinct_id. +- Website docs for the three public `*_LIFECYCLE` tokens ā€” final phase of this spec's plan. + +**Out of scope:** + +- Correlation between `ngaf:postinstall` and cockpit sessions ā€” fundamentally uncorrelatable (different distinct_id sources, anonymous on both sides). `ngaf:postinstall` becomes its own top-of-funnel chart, not an activation step. +- A/B testing, feature flags, experiments in cockpit (deferred ā€” see `gtm.md Ā§11`). +- Persistence across browser refreshes (intentional design ā€” memory-only). +- New cockpit features beyond instrumentation (the 32 example app contents stay the same). +- Marketing-style page analytics (cockpit is an evaluation surface, not a marketing surface). +- Mobile-specific instrumentation paths (mobile users get the same events; no special handling). +- Renaming any `@ngaf/*` libs or restructuring their exports ā€” strictly additive. + +## 4. Architecture + +### 4.1 Three-surface decomposition + +``` +ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā” +ā”‚ COCKPIT REACT SHELL (apps/cockpit, Next.js) ā”‚ +ā”‚ ā”‚ +ā”‚ posthog-js direct (own client, cockpit's PostHog token) ā”‚ +ā”‚ session UUID generated parent-side, memory persistence ā”‚ +ā”‚ ā”‚ +ā”‚ Events: cockpit:recipe_opened, mode_switched, code_copied ā”‚ +ā”‚ ā”‚ +ā”‚ RunMode iframe src = ?cockpit_did=& ā”‚ +ā”‚ cockpit_cap=& ā”‚ +ā”‚ cockpit_phk= ā”‚ +ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¬ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜ + ā”‚ + ā–¼ +ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā” +ā”‚ ANGULAR IFRAME (cockpit///angular) ā”‚ +ā”‚ ā”‚ +ā”‚ main.cockpit.ts ā”€ā”€ā”€ā†’ bootstrapWithCockpitHarness() ā”‚ +ā”‚ (libs/cockpit-telemetry/src/lib/harness.ts)ā”‚ +ā”‚ ā”‚ +ā”‚ Reads URL params ā†’ provideCockpitTelemetry() ā”‚ +ā”‚ posthog-js direct (same distinct_id as parent)ā”‚ +ā”‚ ā”‚ +ā”‚ CockpitTelemetryService subscribes to CHAT_LIFECYCLE, ā”‚ +ā”‚ AGENT_LIFECYCLE, RENDER_LIFECYCLE (all optional injection) ā”‚ +ā”‚ ā”‚ +ā”‚ Events: cockpit:chat_first_message, transport_connected, ā”‚ +ā”‚ thread_persisted, interrupt_handled, ā”‚ +ā”‚ generative_component_rendered ā”‚ +ā”‚ ā”‚ +ā”‚ ActivationAggregator: rolls up to cockpit:activation_complete ā”‚ +ā”‚ when all 5 fire within 30-min window ā”‚ +ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜ +``` + +### 4.2 Repo layout + +``` +NEW +ā”œā”€ā”€ libs/cockpit-telemetry/ # @ngaf/cockpit-telemetry (private) +ā”‚ ā”œā”€ā”€ src/ +ā”‚ ā”‚ ā”œā”€ā”€ index.ts +ā”‚ ā”‚ ā”œā”€ā”€ lib/ +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ harness.ts # bootstrapWithCockpitHarness() +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ provide-cockpit-telemetry.ts # EnvironmentProviders factory +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ cockpit-telemetry.service.ts # subscribes to lifecycle tokens +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ activation-aggregator.ts # 5-signal rollup ā†’ cockpit:activation_complete +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ distinct-id.ts # readCockpitConfigFromIframe() +ā”‚ ā”‚ ā”‚ ā”œā”€ā”€ tokens.ts # COCKPIT_TELEMETRY_CONFIG +ā”‚ ā”‚ ā”‚ ā””ā”€ā”€ events.ts # typed cockpit:* event names +ā”‚ ā”‚ ā””ā”€ā”€ public-api.ts +ā”‚ ā”œā”€ā”€ *.spec.ts +ā”‚ ā”œā”€ā”€ package.json # private: true, @ngaf/cockpit-telemetry +ā”‚ ā”œā”€ā”€ project.json +ā”‚ ā”œā”€ā”€ tsconfig.json +ā”‚ ā”œā”€ā”€ tsconfig.lib.json +ā”‚ ā”œā”€ā”€ ng-package.json +ā”‚ ā”œā”€ā”€ vite.config.mts +ā”‚ ā””ā”€ā”€ README.md # internal docs +ā”‚ +ā”œā”€ā”€ apps/cockpit/src/lib/analytics/ # React shell analytics +ā”‚ ā”œā”€ā”€ client.ts # posthog-js wrapper +ā”‚ ā”œā”€ā”€ events.ts # CockpitShellEvent types +ā”‚ ā”œā”€ā”€ distinct-id.ts # generates session UUID +ā”‚ ā””ā”€ā”€ properties.ts # shouldCaptureAnalytics helper +ā”‚ +ā”œā”€ā”€ apps/cockpit/instrumentation-client.ts # Next.js convention ā€” initializes posthog-js for shell +ā”‚ +MODIFIED +ā”œā”€ā”€ libs/chat/src/lib/ +ā”‚ ā”œā”€ā”€ lifecycle.ts # NEW: CHAT_LIFECYCLE token + interface +ā”‚ ā”œā”€ā”€ compositions/chat/chat.component.ts # populates ChatLifecycle +ā”‚ ā””ā”€ā”€ public-api.ts # exports CHAT_LIFECYCLE +ā”‚ +ā”œā”€ā”€ libs/langgraph/src/lib/ +ā”‚ ā”œā”€ā”€ lifecycle.ts # NEW: AGENT_LIFECYCLE token + interface +ā”‚ ā”œā”€ā”€ agent.fn.ts # populates AgentLifecycle (3 new signals + 5 derived) +ā”‚ ā””ā”€ā”€ public-api.ts # exports AGENT_LIFECYCLE +ā”‚ +ā”œā”€ā”€ libs/render/src/lib/ +ā”‚ ā”œā”€ā”€ lifecycle.ts # NEW: RENDER_LIFECYCLE token + interface +ā”‚ ā”œā”€ā”€ render-lifecycle.service.ts # NEW: subscribes to render-event.ts stream +ā”‚ ā”œā”€ā”€ provide-render.ts # provides RENDER_LIFECYCLE +ā”‚ ā””ā”€ā”€ public-api.ts # exports RENDER_LIFECYCLE +ā”‚ +ā”œā”€ā”€ apps/cockpit/src/components/sidebar/sidebar.tsx +ā”‚ ā””ā”€ā”€ fires cockpit:recipe_opened on capability click +ā”‚ +ā”œā”€ā”€ apps/cockpit/src/components/modes/mode-switcher.tsx +ā”‚ ā””ā”€ā”€ fires cockpit:mode_switched on tab change +ā”‚ +ā”œā”€ā”€ apps/cockpit/src/components/code-mode/code-mode.tsx +ā”‚ ā””ā”€ā”€ fires cockpit:code_copied on Copy button +ā”‚ +ā”œā”€ā”€ apps/cockpit/src/components/narrative-docs/narrative-docs.tsx +ā”‚ ā””ā”€ā”€ fires cockpit:code_copied for both code-snippet + agentic-prompt surfaces +ā”‚ +ā”œā”€ā”€ apps/cockpit/src/components/run-mode/run-mode.tsx +ā”‚ ā””ā”€ā”€ appends cockpit_did/cockpit_cap/cockpit_phk to iframe src +ā”‚ +ā”œā”€ā”€ tsconfig.base.json # path alias for @ngaf/cockpit-telemetry +ā”‚ +ā”œā”€ā”€ docs/gtm/taxonomy.md # drops cockpit:install_command_copied, renames event +ā”œā”€ā”€ tools/posthog/insights/activation-funnel.json # renamed from six-signal-activation-funnel.json; 5 steps +ā”œā”€ā”€ tools/posthog/dashboards/developer-funnel.json # references new insight slug +ā”‚ +ā””ā”€ā”€ cockpit///angular/src/main.cockpit.ts # NEW per example (32 files, ~5 lines each) + ā””ā”€ā”€ project.json # MODIFIED: adds "cockpit" build configuration +``` + +### 4.3 DI architecture rationale + +**Architecture B (lifecycle signals + external adapter).** Libraries expose signals via `InjectionToken`s; an external adapter (`@ngaf/cockpit-telemetry`) subscribes and fires `cockpit:*` events. Reasons: + +1. **Namespace correctness** ā€” `cockpit:*` only fires from cockpit-controlled code. Customer apps consuming `@ngaf/chat` never accidentally emit cockpit-funnel events. +2. **Libraries stay pure** ā€” no new dep on `@ngaf/telemetry` for chat/langgraph/render. Bundles don't grow for non-telemetry users. +3. **Composable signal API** ā€” consumers can subscribe to lifecycle for any purpose (debugging, custom dashboards, custom telemetry vendors); telemetry is one possible subscriber. +4. **Iterative-friendly** ā€” adapter ships first, examples adopt incrementally; library changes don't gate adapter rollout. + +**Why cockpit-telemetry uses `posthog-js` directly, not `@ngaf/telemetry/browser`:** + +- `@ngaf/telemetry/browser` is a customer-facing product telemetry library (its trust contract is "we promise YOUR end-users"). +- Cockpit is our own internal product. Different posture. +- Direct posthog-js use mirrors how the React shell will operate; symmetric architecture. +- Avoids adding `distinctId?` config option to `@ngaf/telemetry/browser`'s public API. + +## 5. Library lifecycle additions + +### 5.1 `CHAT_LIFECYCLE` (`@ngaf/chat`) + +```typescript +// libs/chat/src/lib/lifecycle.ts (NEW) +import { InjectionToken, Signal } from '@angular/core'; + +export interface ChatLifecycle { + readonly componentReady: Signal; + readonly firstMessageSent: Signal; // sticky for life of + readonly messageCount: Signal; // resets on clearThread + readonly inputSubmittedAt: Signal; // resets on clearThread +} + +export const CHAT_LIFECYCLE = new InjectionToken('CHAT_LIFECYCLE'); +``` + +Wired inside `libs/chat/src/lib/compositions/chat/chat.component.ts`. Provided at component level via `{ provide: CHAT_LIFECYCLE, useValue: lifecycle }`. + +Public API additions to `libs/chat/src/public-api.ts`: +- `export { CHAT_LIFECYCLE }` +- `export type { ChatLifecycle }` + +**4 new signals, no derived signals.** + +### 5.2 `AGENT_LIFECYCLE` (`@ngaf/langgraph`) + +```typescript +// libs/langgraph/src/lib/lifecycle.ts (NEW) +export interface AgentLifecycle { + readonly streamStartedAt: Signal; // derived from status$ ā†’ Loadingā†’Success + readonly streamErrorAt: Signal<{ at: number; classification: string } | null>; // derived from error$ + readonly interruptReceivedAt: Signal; // derived from interrupt$ first non-null + readonly interruptResolvedAt: Signal; // NEW: hook in submit({ interrupt }) path + readonly threadCreatedAt: Signal; // NEW: hook on new thread branch + readonly threadPersistedAt: Signal; // NEW: hook on existing-threadId restore + readonly toolCallStartedAt: Signal; // derived from toolCalls$ + readonly toolCallCompletedAt: Signal; // derived from toolCalls$ transition +} + +export const AGENT_LIFECYCLE = new InjectionToken('AGENT_LIFECYCLE'); +``` + +Wired inside `libs/langgraph/src/lib/agent.fn.ts`. The factory builds `AgentLifecycle` alongside the existing BehaviorSubjects + provides it. + +**3 new signal hooks + 5 derived from existing BehaviorSubjects.** + +`threadPersistedAt` fires on the SECOND load of a thread (proves persistence works from the user's perspective), not on the first save. This is the activation-funnel semantic. + +### 5.3 `RENDER_LIFECYCLE` (`@ngaf/render`) + +```typescript +// libs/render/src/lib/lifecycle.ts (NEW) +export interface RenderLifecycle { + readonly firstMountAt: Signal<{ kind: 'spec' | 'element'; elementType?: string; at: number } | null>; + readonly mountCount: Signal; + readonly lastMountAt: Signal; + readonly lastStateChangeAt: Signal; + readonly lastHandlerInvokedAt: Signal<{ action: string; at: number } | null>; +} + +export const RENDER_LIFECYCLE = new InjectionToken('RENDER_LIFECYCLE'); +``` + +A new `RenderLifecycleService` (root-scoped, provided by `provideRender()`) subscribes to the existing `RenderEvent` stream from `render-event.ts` and reduces to signals. `firstMountAt` is sticky for the life of the render context. + +**0 truly new signals ā€” all 5 derive from the existing event stream.** + +## 6. `@ngaf/cockpit-telemetry` internals + +### 6.1 Config tokens + +```typescript +// libs/cockpit-telemetry/src/lib/tokens.ts +export interface CockpitTelemetryConfig { + posthogKey: string; // from URL param cockpit_phk + posthogHost?: string; // from cockpit_host or default + distinctId: string; // session UUID from parent (cockpit_did) + capabilitySlug: string; // e.g. 'langgraph-streaming' (cockpit_cap) + sampleRate?: number; // default 1.0 +} + +export const COCKPIT_TELEMETRY_CONFIG = new InjectionToken( + 'COCKPIT_TELEMETRY_CONFIG', +); +``` + +### 6.2 URL param reader + +```typescript +// libs/cockpit-telemetry/src/lib/distinct-id.ts +export function readCockpitConfigFromIframe(): CockpitTelemetryConfig | null { + const params = new URLSearchParams(window.location.search); + const distinctId = params.get('cockpit_did'); + const posthogKey = params.get('cockpit_phk'); + const capabilitySlug = params.get('cockpit_cap'); + if (!distinctId || !posthogKey || !capabilitySlug) return null; + return { + posthogKey, + posthogHost: params.get('cockpit_host') ?? 'https://us.i.posthog.com', + distinctId, + capabilitySlug, + }; +} +``` + +### 6.3 Bootstrap harness + +```typescript +// libs/cockpit-telemetry/src/lib/harness.ts +export async function bootstrapWithCockpitHarness( + component: Type, + appConfig: ApplicationConfig, +): Promise { + const harness = readCockpitConfigFromIframe(); + const providers = harness + ? [...(appConfig.providers ?? []), provideCockpitTelemetry(harness)] + : appConfig.providers ?? []; + await bootstrapApplication(component, { ...appConfig, providers }); +} +``` + +### 6.4 Provider + service + +```typescript +// libs/cockpit-telemetry/src/lib/provide-cockpit-telemetry.ts +export function provideCockpitTelemetry(config: CockpitTelemetryConfig): EnvironmentProviders { + return makeEnvironmentProviders([ + { provide: COCKPIT_TELEMETRY_CONFIG, useValue: config }, + CockpitTelemetryService, + { + provide: ENVIRONMENT_INITIALIZER, + multi: true, + useFactory: () => { + const svc = inject(CockpitTelemetryService); + return () => svc.init(); + }, + }, + ]); +} +``` + +The service initializes `posthog-js` with `persistence: 'memory'` + `bootstrap.distinctID` from config, then subscribes to all three lifecycle tokens via `inject(TOKEN, null, { optional: true })`. Each subscription is independent ā€” if a token isn't present in the injector tree, the adapter silently skips it. + +Each lifecycle signal transition fires the corresponding `cockpit:*` event AND notifies the aggregator. + +### 6.5 Activation aggregator + +```typescript +// libs/cockpit-telemetry/src/lib/activation-aggregator.ts +const WINDOW_MS = 30 * 60 * 1000; + +type Signal = + | 'transport_connected' + | 'chat_first_message' + | 'thread_persisted' + | 'interrupt_handled' + | 'generative_component_rendered'; + +@Injectable({ providedIn: 'root' }) +export class ActivationAggregator { + // tracks first-signal timestamp + set of seen signals + // fires cockpit:activation_complete when seen.size === 5 within window +} +``` + +**5 signals, not 6.** The PR #328-aware decision: `cockpit:install_command_copied` removed (cockpit doesn't surface install commands; `ngaf:postinstall` is the better signal but uncorrelatable to cockpit sessions). + +### 6.6 Public API + +```typescript +// libs/cockpit-telemetry/src/public-api.ts +export { provideCockpitTelemetry } from './lib/provide-cockpit-telemetry'; +export { bootstrapWithCockpitHarness } from './lib/harness'; +export { readCockpitConfigFromIframe } from './lib/distinct-id'; +export type { CockpitTelemetryConfig } from './lib/tokens'; +``` + +### 6.7 Package manifest + +```json +{ + "name": "@ngaf/cockpit-telemetry", + "version": "0.0.0", + "license": "MIT", + "private": true, + "sideEffects": false, + "type": "module", + "peerDependencies": { + "@angular/core": "^20.0.0 || ^21.0.0" + }, + "dependencies": { + "posthog-js": "^1.373.0" + } +} +``` + +NOT in `nx.json`'s publishable group. Aliased via `tsconfig.base.json` paths so all 32 examples can `import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'` without npm publishing. + +## 7. React shell instrumentation + +### 7.1 Session UUID + memory persistence + +```typescript +// apps/cockpit/src/lib/analytics/distinct-id.ts +let cached: string | null = null; + +export function getCockpitSessionId(): string { + if (!cached) cached = `cockpit_${crypto.randomUUID()}`; + return cached; +} +``` + +Module-state cache. Refresh = new session. No persistence. + +### 7.2 `shouldCaptureAnalytics` helper + +```typescript +// apps/cockpit/src/lib/analytics/properties.ts +export interface CaptureGuardInput { + token: string | undefined; + captureLocal: boolean; + host: string | undefined; + doNotTrack: boolean; +} + +export function shouldCaptureAnalytics(input: CaptureGuardInput): boolean { + if (!input.token) return false; // no token ā†’ no capture + if (input.doNotTrack) return false; // DO_NOT_TRACK ā†’ opt out + if (!input.captureLocal && isLocalhost(input.host)) return false; // localhost gate + return true; +} + +function isLocalhost(host: string | undefined): boolean { + return host === 'localhost' || host?.startsWith('127.0.0.1') || host?.startsWith('0.0.0.0') || false; +} +``` + +### 7.3 Instrumentation client + +```typescript +// apps/cockpit/instrumentation-client.ts +import posthog from 'posthog-js'; +import { getCockpitSessionId } from './src/lib/analytics/distinct-id'; +import { shouldCaptureAnalytics } from './src/lib/analytics/properties'; + +const token = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN; +const captureLocal = process.env.NEXT_PUBLIC_COCKPIT_CAPTURE_LOCAL === 'true'; +const host = typeof window === 'undefined' ? undefined : window.location.host; +const doNotTrack = typeof navigator !== 'undefined' && navigator.doNotTrack === '1'; + +if (shouldCaptureAnalytics({ token, captureLocal, host, doNotTrack })) { + posthog.init(token!, { + api_host: process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_HOST ?? 'https://us.i.posthog.com', + persistence: 'memory', + bootstrap: { distinctID: getCockpitSessionId() }, + autocapture: false, + capture_pageview: false, + }); +} +``` + +### 7.4 Iframe src construction + +```typescript +// apps/cockpit/src/components/run-mode/run-mode.tsx (modified) +function buildIframeSrc(runtimeUrl: string, capabilitySlug: string): string { + const url = new URL(runtimeUrl); + url.searchParams.set('cockpit_did', getCockpitSessionId()); + url.searchParams.set('cockpit_cap', capabilitySlug); + const phk = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_TOKEN; + if (phk) url.searchParams.set('cockpit_phk', phk); + const host = process.env.NEXT_PUBLIC_COCKPIT_POSTHOG_HOST; + if (host) url.searchParams.set('cockpit_host', host); + return url.toString(); +} +``` + +### 7.5 Component fire-on-interaction + +| Component | File | Event | Properties | +|-----------|------|-------|------------| +| Sidebar | `sidebar/sidebar.tsx` | `cockpit:recipe_opened` | `capability`, `category`, `from_capability` | +| Mode switcher | `modes/mode-switcher.tsx` | `cockpit:mode_switched` | `capability`, `from_mode`, `to_mode` | +| Code mode Copy | `code-mode/code-mode.tsx` | `cockpit:code_copied` | `capability`, `surface: 'code_mode'`, `file_path` | +| Docs code snippet Copy | `narrative-docs/narrative-docs.tsx` | `cockpit:code_copied` | `capability`, `surface: 'docs_code_snippet'`, `file_path` | +| Docs agentic prompt Copy | `narrative-docs/narrative-docs.tsx` | `cockpit:code_copied` | `capability`, `surface: 'agentic_prompt'` | + +## 8. `main.cockpit.ts` build override + +### 8.1 The pattern + +Each Angular example gains a `main.cockpit.ts` sibling to `main.ts`. Cockpit Code mode allowlist excludes `main.cockpit.ts` ā€” external developers see only `main.ts`, `app/*.ts`, `*.md`. + +```typescript +// cockpit/langgraph/streaming/angular/src/main.cockpit.ts (NEW per example) +import { StreamingComponent } from './app/streaming.component'; +import { appConfig } from './app/app.config'; +import { bootstrapWithCockpitHarness } from '@ngaf/cockpit-telemetry'; + +bootstrapWithCockpitHarness(StreamingComponent, appConfig); +``` + +If `readCockpitConfigFromIframe()` returns null (no URL params, example opened standalone outside cockpit), the harness bootstraps pristine ā€” telemetry never initializes. + +### 8.2 Per-example `project.json` configuration + +```jsonc +{ + "targets": { + "build": { + "executor": "@angular/build:application", + "configurations": { + "production": { "browser": "src/main.ts", ... }, + "cockpit": { "browser": "src/main.cockpit.ts", ... } // NEW + } + }, + "serve": { + "configurations": { + "production": { "buildTarget": "...:build:production" }, + "cockpit": { "buildTarget": "...:build:cockpit" } // NEW + } + } + } +} +``` + +### 8.3 Cockpit shell serve targets + +The cockpit shell's existing `serve-streaming`, `serve-memory`, etc. targets in `apps/cockpit/project.json` are updated to invoke the `cockpit` configuration: + +```jsonc +"serve-streaming": { + "executor": "@nx/devkit:run-commands", + "options": { + "command": "nx run langgraph-streaming-angular:serve:cockpit" + } +} +``` + +If an example doesn't have a `cockpit` configuration yet (during incremental rollout), the serve target falls back to the default `serve` (no telemetry, but functional). + +## 9. Cross-frame correlation + +### 9.1 Session lifecycle + +``` +1. User opens cockpit ā†’ getCockpitSessionId() generates "cockpit_" + posthog.init(distinct_id="cockpit_") + +2. User clicks "LangGraph / Streaming" ā†’ track('cockpit:recipe_opened', cap=langgraph-streaming) + RunMode renders iframe src with cockpit_did + cockpit_cap + +3. Iframe loads main.cockpit.ts ā†’ readCockpitConfigFromIframe() returns harness config + provideCockpitTelemetry called + iframe's posthog.init(distinct_id="cockpit_") ā€” SAME + +4. User interacts (chat, interrupts) ā†’ CockpitTelemetryService fires cockpit:* events + All share distinct_id="cockpit_" + +5. User switches recipe ā†’ New iframe src, SAME cockpit_did, NEW cockpit_cap + Session continues; new capability tracked + +6. PostHog activation-funnel insight queries by distinct_id ā†’ cohort populated +``` + +### 9.2 Trust + privacy posture + +- **Memory persistence on both frames** ā€” no localStorage, no cookies. Refresh = new session. +- **No PII** ā€” events carry only `capability`/`category`/`file_path`/`surface` strings. No user-supplied content. +- **Cockpit's PostHog token in URL param** ā€” public PostHog project key (write-only event ingestion), safe to expose. Same posture as the website's `NEXT_PUBLIC_POSTHOG_TOKEN`. +- **No telemetry on opt-out** ā€” `shouldCaptureAnalytics()` returns false on token unset, localhost (without explicit override), or `navigator.doNotTrack === '1'`. + +### 9.3 Telemetry defaults + +| Environment | Default state | How to override | +|-------------|---------------|-----------------| +| Production cockpit deploy | **ON** (token env var set, host non-localhost) | n/a | +| Localhost cockpit dev | **OFF** | Set `NEXT_PUBLIC_COCKPIT_CAPTURE_LOCAL=true` | +| Customer's browser with `DO_NOT_TRACK=1` | **OFF** | Disabled by user choice | +| Example loaded standalone (not in iframe) | **OFF** | No URL params; harness bootstraps pristine | + +## 10. Testing strategy + +### 10.1 Test surfaces + counts + +| Surface | Spec files | Tests | +|---------|-----------|-------| +| `libs/chat/src/lib/lifecycle.spec.ts` | 1 | 6 | +| `libs/langgraph/src/lib/lifecycle.spec.ts` | 1 | 10 | +| `libs/render/src/lib/lifecycle.spec.ts` | 1 | 5 | +| `libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.spec.ts` | 1 | 10 | +| `libs/cockpit-telemetry/src/lib/activation-aggregator.spec.ts` | 1 | 6 | +| `libs/cockpit-telemetry/src/lib/distinct-id.spec.ts` | 1 | 4 | +| `libs/cockpit-telemetry/src/lib/harness.spec.ts` | 1 | 3 | +| `libs/cockpit-telemetry/src/lib/browser-silence.spec.ts` | 1 | 1 (permanent) | +| `apps/cockpit/src/lib/analytics/distinct-id.spec.ts` | 1 | 2 | +| `apps/cockpit/src/lib/analytics/client.spec.ts` | 1 | 3 | +| `apps/cockpit/src/lib/analytics/properties.spec.ts` | 1 | 4 | +| Component fire-on-interaction (4 components extended) | 0 new files | 8 | +| Cross-frame correlation | 1 | 3 | +| **Total** | **11 new + 4 modified** | **~65 tests** | + +### 10.2 Permanent contract test + +`libs/cockpit-telemetry/src/lib/browser-silence.spec.ts` asserts: **when `readCockpitConfigFromIframe()` returns null, `posthog.init()` is never called.** Mirrors `@ngaf/telemetry/browser`'s silence test pattern. Stays green permanently ā€” guards against accidental top-level `import 'posthog-js'` polluting bundles. + +### 10.3 Smoke test pattern per example + +Per Phase 4 example rollout: +1. `nx run cockpit:serve` + `nx run cockpit:serve-` locally +2. Chrome MCP navigates to cockpit ā†’ clicks capability +3. Interact with chat / interrupt / generative element as appropriate for the capability +4. Read PostHog Live Events via Chrome MCP; confirm expected `cockpit:*` events arrived with matching distinct_id +5. Commit per-example wiring + +Dispatched per category as a single subagent run. + +### 10.4 CI guard + +Small Bash check in `posthog-sync-plan` job (or its own job): assert every cockpit example's `project.json` either has a `cockpit` build configuration OR is listed in a deferred-rollout allowlist. Catches missing wiring during incremental rollout. + +## 11. Phases (in this spec's plan) + +**Phase 0 ā€” Library lifecycle additions** +- Adds `CHAT_LIFECYCLE`, `AGENT_LIFECYCLE`, `RENDER_LIFECYCLE` +- Lifecycle tests per library (~21 tests) +- Joins the publishable fixed-version group's next bump + +**Phase 1 ā€” `@ngaf/cockpit-telemetry` private library** +- Full adapter, harness, activation aggregator, distinct_id parser +- Unit tests + permanent silence test (~24 tests) +- Added to `tsconfig.base.json` path alias +- NOT added to `nx.json` publishable group + +**Phase 2 ā€” React shell instrumentation** +- `instrumentation-client.ts`, `apps/cockpit/src/lib/analytics/` module +- Four component instrumentations (sidebar, mode-switcher, code-mode, narrative-docs) +- `RunMode` iframe-src construction +- Tests for components + helpers (~17 tests) + +**Phase 3 ā€” Canonical example wired + smoke test** +- `cockpit/langgraph/streaming/angular/src/main.cockpit.ts` +- Updated `project.json` (cockpit config) +- Updated `apps/cockpit/project.json` (serve-streaming uses cockpit config) +- Local Chrome MCP smoke verifying all 5 inner events fire + correlate with parent's distinct_id +- One PR landed; activation funnel begins populating + +**Phase 4 ā€” Roll out remaining 31 examples (batched per category)** +- 4 batches: LangGraph (7 remaining), Deep Agents (6), Chat (5), Render + others (~13) +- Each batch: write `main.cockpit.ts` files + project.json tweaks + smoke test the capability +- 4 commits within this plan + +**Phase 5 ā€” Website docs for `*_LIFECYCLE` tokens** +- New docs pages at `/docs//lifecycle` on cacheplane.ai for chat, langgraph, render +- Each page: typed interface, semantics of each signal, code example for subscribing +- Links from each lib's existing landing page +- Aligns with post-#328 "no app telemetry by default" framing + +**Phase 6 ā€” Taxonomy + dashboard JSON cleanup** +- `docs/gtm/taxonomy.md`: remove `cockpit:install_command_copied`, rename `cockpit:six_signals_complete` ā†’ `cockpit:activation_complete` +- `tools/posthog/insights/six-signal-activation-funnel.json` ā†’ rename to `activation-funnel.json`, update steps to 5 +- `tools/posthog/dashboards/developer-funnel.json`: update insight slug reference +- `npm run posthog:sync -- --plan` in CI verifies; one operator `posthog:sync --apply` rolls live PostHog + +## 12. Risks & non-goals + +### 12.1 Risks + +| # | Risk | Mitigation | +|--:|------|------------| +| 1 | Lifecycle signals drift from library behavior in future refactors | Signals populated by same code paths as feature behavior; lib's own tests catch regressions | +| 2 | `cockpit` build configuration breaks an example's standalone deploy | Default `production` config unchanged; `cockpit` is purely additive; smoke test verifies both still work | +| 3 | Cross-frame distinct_id in URL params shows in browser history | UUIDs anonymous + per-session; data is low-value; memory persistence means refresh = new session | +| 4 | Future Angular major version breaks a lifecycle token | Standard Angular DI; bumps follow the existing fixed-group cadence | +| 5 | Example uses something custom (not `@ngaf/chat`) ā€” adapter subscribes to absent token | `injector.get(TOKEN, null, { optional: true })` returns null gracefully; adapter no-ops | +| 6 | Cockpit's posthog token leaks via URL `?cockpit_phk=` | Token is the public PostHog project key (write-only ingestion), safe to expose | +| 7 | 30-minute window math drifts under clock skew | Uses `Date.now()` (epoch ms, monotonic in practice); aggregator resets on stale signal | +| 8 | Phase 4 rollout stalls partway | Examples without `main.cockpit.ts` still work in cockpit (no telemetry, functional); follow-up PRs can complete rollout | +| 9 | `ngaf:postinstall` and `cockpit:*` events are NEVER correlatable | Intentional; documented; `ngaf:postinstall` is a separate top-of-funnel chart, not an activation step | + +### 12.2 Non-goals + +- No correlation between `ngaf:postinstall` and cockpit sessions (uncorrelatable by design) +- No A/B testing or experiments in cockpit +- No persistence across browser refreshes (memory-only by design) +- No marketing-style page analytics (cockpit is an evaluation surface) +- No automatic example deployment changes (`cockpit` build is build-time only) +- No public API for cockpit-telemetry adapter (private, may break freely) +- No telemetry from cockpit's Next.js API routes (only React shell + iframe instrumented) +- No mobile-specific tracking paths + +### 12.3 Deferred (NOT in this spec) + +- Outer-shell engagement insights (which capabilities have highest mode-switch rates) ā€” follow-up `dashboards-content` spec +- A/B testing of cockpit copy / layout ā€” `feature-flags-as-code` spec (gtm.md Ā§11) +- New `cockpit:*` events beyond the design ā€” handled by existing event-name pattern as added + +## 13. Deliverables of this spec + +Plan at `docs/superpowers/plans/gtm/2026-05-15-analytics-foundation-1c-cockpit-instrumentation.md` will check off: + +- [ ] **Phase 0:** `CHAT_LIFECYCLE`, `AGENT_LIFECYCLE`, `RENDER_LIFECYCLE` tokens + interfaces + lib internal wiring + tests (~21 tests across 3 libs) +- [ ] **Phase 1:** `libs/cockpit-telemetry/` (private, `@ngaf/cockpit-telemetry`); harness, provider, service, aggregator, distinct-id, tokens; ~24 tests including permanent silence +- [ ] **Phase 1 follow-on:** `tsconfig.base.json` path alias; ng-package.json; project.json; vite.config.mts +- [ ] **Phase 2:** `apps/cockpit/src/lib/analytics/` (distinct-id, client, events, properties); `apps/cockpit/instrumentation-client.ts`; 4 component instrumentations; ~17 tests +- [ ] **Phase 3:** canonical streaming example: `cockpit/langgraph/streaming/angular/src/main.cockpit.ts` + project.json cockpit config; update `apps/cockpit/project.json` serve-streaming; smoke test via Chrome MCP +- [ ] **Phase 4:** 31 remaining examples wired in 4 category batches: LangGraph, Deep Agents, Chat, Render+others +- [ ] **Phase 5:** website docs for the three `*_LIFECYCLE` tokens at `/docs//lifecycle` +- [ ] **Phase 6:** `docs/gtm/taxonomy.md` updates; `tools/posthog/insights/activation-funnel.json` (renamed from six-signal-activation-funnel.json, 5 steps); `tools/posthog/dashboards/developer-funnel.json` reference update; CI sync-plan green; operator runs apply + +## 14. References + +- Parent: [docs/superpowers/specs/gtm/2026-05-13-gtm-meta-design.md](2026-05-13-gtm-meta-design.md) +- Sibling 1A (shipped): [docs/superpowers/specs/gtm/2026-05-14-analytics-foundation-1a-dashboards-as-code-design.md](2026-05-14-analytics-foundation-1a-dashboards-as-code-design.md) +- Sibling 1B (shipped): [docs/superpowers/specs/gtm/2026-05-15-analytics-foundation-1b-ngaf-telemetry-design.md](2026-05-15-analytics-foundation-1b-ngaf-telemetry-design.md) +- PR #328 (on main as `ba4904f2`): `feat(telemetry): capture installs from published packages` ā€” adds `/api/ingest` proxy, ships `ngaf:postinstall` from every package, drops `posthog-node` from `@ngaf/telemetry` +- Strategy: [gtm.md](../../../../gtm.md) +- Taxonomy: [docs/gtm/taxonomy.md](../../../gtm/taxonomy.md) +- Existing developer-funnel dashboard: `tools/posthog/dashboards/developer-funnel.json` +- Existing cockpit Run mode: `apps/cockpit/src/components/run-mode/run-mode.tsx` +- Existing chat component: `libs/chat/src/lib/compositions/chat/chat.component.ts` +- Existing agent factory: `libs/langgraph/src/lib/agent.fn.ts` +- Existing render event stream: `libs/render/src/lib/render-event.ts` diff --git a/libs/chat/src/lib/compositions/chat/chat.component.ts b/libs/chat/src/lib/compositions/chat/chat.component.ts index da7761300..4af9adfc9 100644 --- a/libs/chat/src/lib/compositions/chat/chat.component.ts +++ b/libs/chat/src/lib/compositions/chat/chat.component.ts @@ -35,6 +35,35 @@ import { createA2uiSurfaceStore, type A2uiSurfaceStore } from '../../a2ui/surfac import { messageContent } from '../shared/message-utils'; import { CHAT_HOST_TOKENS } from '../../styles/chat-tokens'; import type { ChatRenderEvent } from './chat-render-event'; +import { CHAT_LIFECYCLE, type ChatLifecycle } from '../../lifecycle'; + +/** + * Internal helper: WritableSignals backing the readonly ChatLifecycle surface + * exposed via CHAT_LIFECYCLE. ChatComponent populates these as the user + * interacts; consumers (e.g. cockpit-telemetry) only see the readonly view. + */ +interface ChatLifecycleInternal extends ChatLifecycle { + _internal: { + componentReady: ReturnType>; + firstMessageSent: ReturnType>; + messageCount: ReturnType>; + inputSubmittedAt: ReturnType>; + }; +} + +function createChatLifecycle(): ChatLifecycleInternal { + const componentReady = signal(false); + const firstMessageSent = signal(false); + const messageCount = signal(0); + const inputSubmittedAt = signal(null); + return { + componentReady: componentReady.asReadonly(), + firstMessageSent: firstMessageSent.asReadonly(), + messageCount: messageCount.asReadonly(), + inputSubmittedAt: inputSubmittedAt.asReadonly(), + _internal: { componentReady, firstMessageSent, messageCount, inputSubmittedAt }, + }; +} /** * Returns true when the scroll position is within `tolerance` px of the bottom. @@ -62,6 +91,9 @@ export function isPinned( ChatScrollBubbleComponent, ], changeDetection: ChangeDetectionStrategy.OnPush, + providers: [ + { provide: CHAT_LIFECYCLE, useFactory: createChatLifecycle }, + ], styles: [CHAT_HOST_TOKENS, ` :host { display: flex; @@ -339,6 +371,10 @@ export class ChatComponent { private readonly classifiers = new Map(); private readonly destroyRef = inject(DestroyRef); + // Resolved against the component's own `providers` in normal use. The fallback + // is for tests that construct ChatComponent via `new` inside a bare injection + // context (no element injector, so component-level providers are skipped). + private readonly lifecycle = (inject(CHAT_LIFECYCLE, { optional: true }) ?? createChatLifecycle()) as ChatLifecycleInternal; private eventsSubscribed = false; /** @@ -364,6 +400,7 @@ export class ChatComponent { let agent: ReturnType; try { agent = this.agent(); } catch { return; } this.eventsSubscribed = true; + this.lifecycle._internal.componentReady.set(true); agent.events$.pipe(takeUntilDestroyed(this.destroyRef)).subscribe((event) => { if (event.type !== 'state_update') return; const store = this.resolvedStore(); @@ -495,6 +532,39 @@ export class ChatComponent { protected onUserSubmitted(): void { this.pinned.set(true); + this.recordSubmit(); + } + + /** + * Programmatic submit. Calls `agent.submit({ message: text })` and updates + * the CHAT_LIFECYCLE signals. Trimmed-empty text is a no-op. + */ + submitMessage(text: string): void { + const trimmed = text.trim(); + if (!trimmed) return; + void this.agent().submit({ message: trimmed }); + this.recordSubmit(); + } + + /** + * Clears local view state (classifiers, surface store, lifecycle counters) + * for a new thread. + * + * Resets messageCount to 0 and inputSubmittedAt to null. componentReady and + * firstMessageSent are NOT reset (sticky for the chat instance lifetime). + */ + clearThread(): void { + this.clearClassifiers(); + this.lifecycle._internal.messageCount.set(0); + this.lifecycle._internal.inputSubmittedAt.set(null); + } + + private recordSubmit(): void { + if (!this.lifecycle._internal.firstMessageSent()) { + this.lifecycle._internal.firstMessageSent.set(true); + } + this.lifecycle._internal.messageCount.update((c) => c + 1); + this.lifecycle._internal.inputSubmittedAt.set(Date.now()); } /** diff --git a/libs/chat/src/lib/lifecycle.spec.ts b/libs/chat/src/lib/lifecycle.spec.ts new file mode 100644 index 000000000..cd3b62d98 --- /dev/null +++ b/libs/chat/src/lib/lifecycle.spec.ts @@ -0,0 +1,73 @@ +// @vitest-environment jsdom +// SPDX-License-Identifier: MIT +import { describe, test, expect, beforeEach } from 'vitest'; +import { TestBed, type ComponentFixture } from '@angular/core/testing'; +import { ChatComponent } from './compositions/chat/chat.component'; +import { CHAT_LIFECYCLE, type ChatLifecycle } from './lifecycle'; +import { mockAgent } from './testing/mock-agent'; + +describe('ChatLifecycle integration', () => { + let fixture: ComponentFixture; + let chatRef: ChatComponent; + let lifecycle: ChatLifecycle; + + beforeEach(() => { + TestBed.configureTestingModule({}); + fixture = TestBed.createComponent(ChatComponent); + chatRef = fixture.componentInstance; + fixture.componentRef.setInput('agent', mockAgent()); + fixture.detectChanges(); + // CHAT_LIFECYCLE is component-scoped ā€” read it from the component's injector. + lifecycle = fixture.componentRef.injector.get(CHAT_LIFECYCLE); + }); + + test('componentReady is true after ChatComponent initializes with an agent', () => { + expect(lifecycle.componentReady()).toBe(true); + }); + + test('firstMessageSent starts false', () => { + // Re-create a fresh fixture so we observe the initial value before any submit. + const f = TestBed.createComponent(ChatComponent); + f.componentRef.setInput('agent', mockAgent()); + f.detectChanges(); + const lc = f.componentRef.injector.get(CHAT_LIFECYCLE); + expect(lc.firstMessageSent()).toBe(false); + }); + + test('firstMessageSent flips to true after first submitMessage and stays true', () => { + chatRef.submitMessage('hello'); + expect(lifecycle.firstMessageSent()).toBe(true); + chatRef.submitMessage('again'); + expect(lifecycle.firstMessageSent()).toBe(true); + }); + + test('messageCount increments on each submit', () => { + chatRef.submitMessage('one'); + chatRef.submitMessage('two'); + chatRef.submitMessage('three'); + expect(lifecycle.messageCount()).toBe(3); + }); + + test('messageCount resets on clearThread but firstMessageSent stays true', () => { + chatRef.submitMessage('one'); + chatRef.clearThread(); + expect(lifecycle.messageCount()).toBe(0); + expect(lifecycle.firstMessageSent()).toBe(true); + }); + + test('inputSubmittedAt updates on submit and resets to null on clearThread', () => { + expect(lifecycle.inputSubmittedAt()).toBe(null); + chatRef.submitMessage('one'); + expect(lifecycle.inputSubmittedAt()).toBeGreaterThan(0); + chatRef.clearThread(); + expect(lifecycle.inputSubmittedAt()).toBe(null); + }); + + test('onUserSubmitted increments messageCount and flips firstMessageSent to true', () => { + expect(lifecycle.messageCount()).toBe(0); + expect(lifecycle.firstMessageSent()).toBe(false); + chatRef.onUserSubmitted(); + expect(lifecycle.messageCount()).toBe(1); + expect(lifecycle.firstMessageSent()).toBe(true); + }); +}); diff --git a/libs/chat/src/lib/lifecycle.ts b/libs/chat/src/lib/lifecycle.ts new file mode 100644 index 000000000..da3058cea --- /dev/null +++ b/libs/chat/src/lib/lifecycle.ts @@ -0,0 +1,16 @@ +// SPDX-License-Identifier: MIT + +import { InjectionToken, Signal } from '@angular/core'; + +export interface ChatLifecycle { + /** True after `` initializes with a non-null agent binding. */ + readonly componentReady: Signal; + /** True after the first user submit. Sticky for the life of the chat instance ā€” does NOT reset on clearThread. */ + readonly firstMessageSent: Signal; + /** Count of user submits. Resets on clearThread. */ + readonly messageCount: Signal; + /** Epoch ms of the most recent user submit. Resets on clearThread. */ + readonly inputSubmittedAt: Signal; +} + +export const CHAT_LIFECYCLE = new InjectionToken('CHAT_LIFECYCLE'); diff --git a/libs/chat/src/public-api.ts b/libs/chat/src/public-api.ts index 5486ef6aa..aa2c6572e 100644 --- a/libs/chat/src/public-api.ts +++ b/libs/chat/src/public-api.ts @@ -77,6 +77,10 @@ export { ChatCitationsCardComponent } from './lib/primitives/chat-citations/chat // DI provider export { provideChat, CHAT_CONFIG } from './lib/provide-chat'; +// Lifecycle +export { CHAT_LIFECYCLE } from './lib/lifecycle'; +export type { ChatLifecycle } from './lib/lifecycle'; + // Compositions export { ChatComponent } from './lib/compositions/chat/chat.component'; export type { ChatRenderEvent } from './lib/compositions/chat/chat-render-event'; diff --git a/libs/cockpit-telemetry/README.md b/libs/cockpit-telemetry/README.md new file mode 100644 index 000000000..d01b2ac94 --- /dev/null +++ b/libs/cockpit-telemetry/README.md @@ -0,0 +1,17 @@ +# @ngaf/cockpit-telemetry + +Private Nx library. **Not** part of the publishable `@ngaf/*` group ā€” it is consumed only by the cockpit-harness build of the framework's example apps (the 32 Angular examples rendered inside the cockpit iframe). + +## What it does + +When the parent cockpit shell embeds an example as an iframe, it appends URL params (`cockpit_did`, `cockpit_phk`, `cockpit_cap`, optional `cockpit_host`). The example's `main.cockpit.ts` calls `bootstrapWithCockpitHarness`, which: + +1. Reads those params via `readCockpitConfigFromIframe()`. +2. If present, registers `provideCockpitTelemetry(config)` and the service initializes PostHog (memory persistence, parent-provided `distinct_id`) on app bootstrap. +3. Subscribes to optional `CHAT_LIFECYCLE`, `AGENT_LIFECYCLE`, and `RENDER_LIFECYCLE` signals from `@ngaf/chat`, `@ngaf/langgraph`, and `@ngaf/render` and emits `cockpit:*` events. + +## No app telemetry by default + +The framework ships with **zero telemetry** in user apps. This library only activates inside the cockpit harness. The pristine `main.ts` of each example never imports `posthog-js`. The `browser-silence.spec.ts` test enforces this contract. + +See `libs/telemetry/README.md` for the parallel pattern in the public telemetry library. diff --git a/libs/cockpit-telemetry/eslint.config.mjs b/libs/cockpit-telemetry/eslint.config.mjs new file mode 100644 index 000000000..2a5a0fc84 --- /dev/null +++ b/libs/cockpit-telemetry/eslint.config.mjs @@ -0,0 +1,44 @@ +import nx from '@nx/eslint-plugin'; +import baseConfig from '../../eslint.config.mjs'; + +export default [ + ...baseConfig, + { + files: ['**/*.json'], + rules: { + '@nx/dependency-checks': [ + 'error', + { + ignoredFiles: ['{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}'], + ignoredDependencies: ['vite', '@nx/vite', 'vitest', '@analogjs/vite-plugin-angular'], + }, + ], + }, + languageOptions: { + parser: await import('jsonc-eslint-parser'), + }, + }, + ...nx.configs['flat/angular'], + ...nx.configs['flat/angular-template'], + { + files: ['**/*.ts'], + rules: { + '@angular-eslint/directive-selector': [ + 'error', + { + type: 'attribute', + prefix: ['lib'], + style: 'camelCase', + }, + ], + '@angular-eslint/component-selector': [ + 'error', + { + type: 'element', + prefix: ['lib'], + style: 'kebab-case', + }, + ], + }, + }, +]; diff --git a/libs/cockpit-telemetry/ng-package.json b/libs/cockpit-telemetry/ng-package.json new file mode 100644 index 000000000..564de930a --- /dev/null +++ b/libs/cockpit-telemetry/ng-package.json @@ -0,0 +1,8 @@ +{ + "$schema": "../../node_modules/ng-packagr/ng-package.schema.json", + "dest": "../../dist/libs/cockpit-telemetry", + "lib": { + "entryFile": "src/public-api.ts" + }, + "allowedNonPeerDependencies": ["posthog-js"] +} diff --git a/libs/cockpit-telemetry/package.json b/libs/cockpit-telemetry/package.json new file mode 100644 index 000000000..af53e06b0 --- /dev/null +++ b/libs/cockpit-telemetry/package.json @@ -0,0 +1,18 @@ +{ + "name": "@ngaf/cockpit-telemetry", + "version": "0.0.0", + "license": "MIT", + "private": true, + "sideEffects": false, + "type": "module", + "peerDependencies": { + "@angular/core": "^20.0.0 || ^21.0.0", + "@angular/platform-browser": "^20.0.0 || ^21.0.0", + "@ngaf/chat": "*", + "@ngaf/langgraph": "*", + "@ngaf/render": "*" + }, + "dependencies": { + "posthog-js": "^1.373.0" + } +} diff --git a/libs/cockpit-telemetry/project.json b/libs/cockpit-telemetry/project.json new file mode 100644 index 000000000..566705690 --- /dev/null +++ b/libs/cockpit-telemetry/project.json @@ -0,0 +1,27 @@ +{ + "name": "cockpit-telemetry", + "$schema": "../../node_modules/nx/schemas/project-schema.json", + "sourceRoot": "libs/cockpit-telemetry/src", + "prefix": "lib", + "projectType": "library", + "tags": [], + "targets": { + "build": { + "executor": "@nx/angular:package", + "outputs": ["{workspaceRoot}/dist/libs/cockpit-telemetry"], + "options": { + "project": "libs/cockpit-telemetry/ng-package.json", + "tsConfig": "libs/cockpit-telemetry/tsconfig.lib.json" + } + }, + "test": { + "executor": "@nx/vitest:test", + "options": { + "configFile": "libs/cockpit-telemetry/vite.config.mts" + } + }, + "lint": { + "executor": "@nx/eslint:lint" + } + } +} diff --git a/libs/cockpit-telemetry/src/index.ts b/libs/cockpit-telemetry/src/index.ts new file mode 100644 index 000000000..db63d0b81 --- /dev/null +++ b/libs/cockpit-telemetry/src/index.ts @@ -0,0 +1,2 @@ +// SPDX-License-Identifier: MIT +export * from './public-api'; diff --git a/libs/cockpit-telemetry/src/lib/activation-aggregator.spec.ts b/libs/cockpit-telemetry/src/lib/activation-aggregator.spec.ts new file mode 100644 index 000000000..4eda2e991 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/activation-aggregator.spec.ts @@ -0,0 +1,113 @@ +// SPDX-License-Identifier: MIT +// @vitest-environment jsdom +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { ActivationAggregator } from './activation-aggregator'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; + +vi.mock('posthog-js', () => ({ + default: { capture: vi.fn() }, +})); + +import posthog from 'posthog-js'; + +describe('ActivationAggregator', () => { + let aggregator: ActivationAggregator; + + beforeEach(() => { + vi.mocked(posthog.capture).mockClear(); + TestBed.configureTestingModule({ + providers: [ + { + provide: COCKPIT_TELEMETRY_CONFIG, + useValue: { posthogKey: 'k', distinctId: 'd', capabilitySlug: 'streaming' }, + }, + ActivationAggregator, + ], + }); + aggregator = TestBed.inject(ActivationAggregator); + }); + + test('does not fire activation_complete before all 5 signals', () => { + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('transport_connected'); + aggregator.markSignal('thread_persisted'); + expect(posthog.capture).not.toHaveBeenCalled(); + }); + + test('fires activation_complete exactly once when all 5 signals seen', () => { + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('transport_connected'); + aggregator.markSignal('thread_persisted'); + aggregator.markSignal('interrupt_handled'); + aggregator.markSignal('generative_component_rendered'); + expect(posthog.capture).toHaveBeenCalledTimes(1); + expect(posthog.capture).toHaveBeenCalledWith( + 'cockpit:activation_complete', + expect.any(Object), + ); + }); + + test('subsequent signals after complete do not re-fire', () => { + for (const sig of [ + 'chat_first_message', + 'transport_connected', + 'thread_persisted', + 'interrupt_handled', + 'generative_component_rendered', + ] as const) { + aggregator.markSignal(sig); + } + aggregator.markSignal('chat_first_message'); + expect(posthog.capture).toHaveBeenCalledTimes(1); + }); + + test('duplicate signals are idempotent', () => { + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('chat_first_message'); + aggregator.markSignal('transport_connected'); + aggregator.markSignal('transport_connected'); + expect(posthog.capture).not.toHaveBeenCalled(); + }); + + test('30-min window: stale first signal resets when newer one arrives outside window', () => { + const real = Date.now; + let now = 1_000_000; + Date.now = () => now; + try { + aggregator.markSignal('chat_first_message'); + now += 31 * 60 * 1000; // 31 min later + aggregator.markSignal('transport_connected'); + // chat_first_message has expired; only transport_connected is in the current window + now += 1000; + aggregator.markSignal('thread_persisted'); + aggregator.markSignal('interrupt_handled'); + aggregator.markSignal('generative_component_rendered'); + // Need chat_first_message in this window too + expect(posthog.capture).not.toHaveBeenCalled(); + aggregator.markSignal('chat_first_message'); + expect(posthog.capture).toHaveBeenCalled(); + } finally { + Date.now = real; + } + }); + + test('emits duration_ms property when activation_complete fires', () => { + const real = Date.now; + let now = 5_000_000; + Date.now = () => now; + try { + aggregator.markSignal('chat_first_message'); + now += 1234; + aggregator.markSignal('transport_connected'); + aggregator.markSignal('thread_persisted'); + aggregator.markSignal('interrupt_handled'); + aggregator.markSignal('generative_component_rendered'); + const call = vi.mocked(posthog.capture).mock.calls[0]; + expect((call[1] as Record)['duration_ms']).toBe(1234); + expect((call[1] as Record)['capability']).toBe('streaming'); + } finally { + Date.now = real; + } + }); +}); diff --git a/libs/cockpit-telemetry/src/lib/activation-aggregator.ts b/libs/cockpit-telemetry/src/lib/activation-aggregator.ts new file mode 100644 index 000000000..21540b60f --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/activation-aggregator.ts @@ -0,0 +1,44 @@ +// SPDX-License-Identifier: MIT +import { Injectable, inject } from '@angular/core'; +import posthog from 'posthog-js'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; + +const WINDOW_MS = 30 * 60 * 1000; + +export type ActivationSignal = + | 'transport_connected' + | 'chat_first_message' + | 'thread_persisted' + | 'interrupt_handled' + | 'generative_component_rendered'; + +@Injectable() +export class ActivationAggregator { + private config = inject(COCKPIT_TELEMETRY_CONFIG); + private windowStartAt: number | null = null; + private seen = new Set(); + private complete = false; + + markSignal(signal: ActivationSignal): void { + if (this.complete) return; + const now = Date.now(); + // If first signal of window, anchor; if outside window, reset. + if (this.windowStartAt === null || now - this.windowStartAt > WINDOW_MS) { + this.windowStartAt = now; + this.seen.clear(); + } + this.seen.add(signal); + if (this.seen.size === 5) { + this.complete = true; + const durationMs = now - this.windowStartAt; + try { + posthog.capture('cockpit:activation_complete', { + capability: this.config.capabilitySlug, + duration_ms: durationMs, + }); + } catch { + // silent fail + } + } + } +} diff --git a/libs/cockpit-telemetry/src/lib/browser-silence.spec.ts b/libs/cockpit-telemetry/src/lib/browser-silence.spec.ts new file mode 100644 index 000000000..d05e74d18 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/browser-silence.spec.ts @@ -0,0 +1,18 @@ +// SPDX-License-Identifier: MIT +// @vitest-environment jsdom +import { describe, test, expect, vi } from 'vitest'; +import { readCockpitConfigFromIframe } from './distinct-id'; + +// If anything in this module's static import graph pulls posthog-js, the +// factory below throws at evaluation time and the spec file fails to load. +vi.mock('posthog-js', () => { + throw new Error('posthog-js MUST NOT be imported when no cockpit URL params are present'); +}); + +describe('browser silence (permanent contract)', () => { + test('no posthog-js import triggered by readCockpitConfigFromIframe when no URL params', () => { + // No-op URL params ā€” just reads window.location.search. + expect(readCockpitConfigFromIframe()).toBe(null); + // posthog-js mock has thrown by now if it was imported eagerly. + }); +}); diff --git a/libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.spec.ts b/libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.spec.ts new file mode 100644 index 000000000..ad505af17 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.spec.ts @@ -0,0 +1,252 @@ +// SPDX-License-Identifier: MIT +// @vitest-environment jsdom +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { signal } from '@angular/core'; +import { CockpitTelemetryService } from './cockpit-telemetry.service'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; +import { ActivationAggregator } from './activation-aggregator'; +import { CHAT_LIFECYCLE, type ChatLifecycle } from '@ngaf/chat'; +import { AgentLifecycleRegistry, type AgentLifecycle } from '@ngaf/langgraph'; + +function makeAgentLifecycle(): AgentLifecycle & { + _setStreamStarted: () => void; + _setThreadPersisted: () => void; + _setInterruptResolved: () => void; +} { + const streamStartedAt = signal(null); + const threadPersistedAt = signal(null); + const interruptResolvedAt = signal(null); + return { + streamStartedAt: streamStartedAt.asReadonly(), + streamErrorAt: signal<{ at: number; classification: string } | null>(null).asReadonly(), + interruptReceivedAt: signal(null).asReadonly(), + interruptResolvedAt: interruptResolvedAt.asReadonly(), + threadCreatedAt: signal(null).asReadonly(), + threadPersistedAt: threadPersistedAt.asReadonly(), + toolCallStartedAt: signal(null).asReadonly(), + toolCallCompletedAt: signal(null).asReadonly(), + _setStreamStarted: () => streamStartedAt.set(Date.now()), + _setThreadPersisted: () => threadPersistedAt.set(Date.now()), + _setInterruptResolved: () => interruptResolvedAt.set(Date.now()), + }; +} + +const mocks = vi.hoisted(() => ({ + init: vi.fn(), + capture: vi.fn(), +})); + +vi.mock('posthog-js', () => ({ + default: { init: mocks.init, capture: mocks.capture }, +})); + +function makeChatLifecycle(): ChatLifecycle & { _setFirstMessage: () => void } { + const firstMessageSent = signal(false); + return { + componentReady: signal(true).asReadonly(), + firstMessageSent: firstMessageSent.asReadonly(), + messageCount: signal(0).asReadonly(), + inputSubmittedAt: signal(null).asReadonly(), + _setFirstMessage: () => firstMessageSent.set(true), + }; +} + +describe('CockpitTelemetryService', () => { + let svc: CockpitTelemetryService; + let chat: ReturnType; + + beforeEach(() => { + mocks.init.mockClear(); + mocks.capture.mockClear(); + chat = makeChatLifecycle(); + TestBed.configureTestingModule({ + providers: [ + { + provide: COCKPIT_TELEMETRY_CONFIG, + useValue: { posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming' }, + }, + ActivationAggregator, + { provide: CHAT_LIFECYCLE, useValue: chat }, + CockpitTelemetryService, + ], + }); + svc = TestBed.inject(CockpitTelemetryService); + }); + + test('init() initializes posthog-js with memory persistence + bootstrap distinctID', () => { + svc.init(); + expect(mocks.init).toHaveBeenCalledWith( + 'phc_test', + expect.objectContaining({ + persistence: 'memory', + bootstrap: { distinctID: 'd1' }, + autocapture: false, + capture_pageview: false, + }), + ); + }); + + test('init() is idempotent', () => { + svc.init(); + svc.init(); + expect(mocks.init).toHaveBeenCalledTimes(1); + }); + + test('fires cockpit:chat_first_message when ChatLifecycle.firstMessageSent flips to true', async () => { + svc.init(); + chat._setFirstMessage(); + TestBed.tick(); + await Promise.resolve(); + expect(mocks.capture).toHaveBeenCalledWith( + 'cockpit:chat_first_message', + expect.objectContaining({ capability: 'streaming' }), + ); + }); + + test('does not fire if lifecycle was already-true at init time and never transitions', async () => { + chat._setFirstMessage(); // before init + svc.init(); + TestBed.tick(); + await Promise.resolve(); + // Effect runs once, captures the current state ā€” fire-on-init is allowed. + // The contract is "fires once at most". + const calls = mocks.capture.mock.calls.filter(([e]) => e === 'cockpit:chat_first_message'); + expect(calls.length).toBeLessThanOrEqual(1); + }); + + test('no lifecycle present ā†’ no events fire', () => { + TestBed.resetTestingModule(); + TestBed.configureTestingModule({ + providers: [ + { + provide: COCKPIT_TELEMETRY_CONFIG, + useValue: { posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming' }, + }, + ActivationAggregator, + CockpitTelemetryService, + ], + }); + const svc2 = TestBed.inject(CockpitTelemetryService); + svc2.init(); + expect(mocks.capture).not.toHaveBeenCalled(); + }); + + test('captures include capability property from config', async () => { + svc.init(); + chat._setFirstMessage(); + TestBed.tick(); + await Promise.resolve(); + const call = mocks.capture.mock.calls.find(([e]) => e === 'cockpit:chat_first_message'); + expect((call?.[1] as Record)['capability']).toBe('streaming'); + }); + + test('no AgentLifecycleRegistry provided ā†’ no agent events fire', () => { + TestBed.resetTestingModule(); + TestBed.configureTestingModule({ + providers: [ + { + provide: COCKPIT_TELEMETRY_CONFIG, + useValue: { posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming' }, + }, + ActivationAggregator, + CockpitTelemetryService, + ], + }); + const svc2 = TestBed.inject(CockpitTelemetryService); + svc2.init(); + expect(mocks.capture).not.toHaveBeenCalledWith( + 'cockpit:transport_connected', + expect.anything(), + ); + }); + + test('fires cockpit:transport_connected when a registered agent lifecycle streamStartedAt flips', async () => { + TestBed.resetTestingModule(); + const registry = new AgentLifecycleRegistry(); + TestBed.configureTestingModule({ + providers: [ + { + provide: COCKPIT_TELEMETRY_CONFIG, + useValue: { posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming' }, + }, + ActivationAggregator, + { provide: AgentLifecycleRegistry, useValue: registry }, + CockpitTelemetryService, + ], + }); + const svc2 = TestBed.inject(CockpitTelemetryService); + svc2.init(); + const lifecycle = makeAgentLifecycle(); + registry.register(lifecycle); + TestBed.tick(); + await Promise.resolve(); + lifecycle._setStreamStarted(); + TestBed.tick(); + await Promise.resolve(); + expect(mocks.capture).toHaveBeenCalledWith( + 'cockpit:transport_connected', + expect.objectContaining({ capability: 'streaming' }), + ); + }); + + test('fires cockpit:thread_persisted and cockpit:interrupt_handled for registered agents', async () => { + TestBed.resetTestingModule(); + const registry = new AgentLifecycleRegistry(); + TestBed.configureTestingModule({ + providers: [ + { + provide: COCKPIT_TELEMETRY_CONFIG, + useValue: { posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming' }, + }, + ActivationAggregator, + { provide: AgentLifecycleRegistry, useValue: registry }, + CockpitTelemetryService, + ], + }); + const svc2 = TestBed.inject(CockpitTelemetryService); + svc2.init(); + const lifecycle = makeAgentLifecycle(); + registry.register(lifecycle); + TestBed.tick(); + await Promise.resolve(); + lifecycle._setThreadPersisted(); + lifecycle._setInterruptResolved(); + TestBed.tick(); + await Promise.resolve(); + expect(mocks.capture).toHaveBeenCalledWith('cockpit:thread_persisted', expect.anything()); + expect(mocks.capture).toHaveBeenCalledWith('cockpit:interrupt_handled', expect.anything()); + }); + + test('subscribes to lifecycles registered AFTER init', async () => { + TestBed.resetTestingModule(); + const registry = new AgentLifecycleRegistry(); + TestBed.configureTestingModule({ + providers: [ + { + provide: COCKPIT_TELEMETRY_CONFIG, + useValue: { posthogKey: 'phc_test', distinctId: 'd1', capabilitySlug: 'streaming' }, + }, + ActivationAggregator, + { provide: AgentLifecycleRegistry, useValue: registry }, + CockpitTelemetryService, + ], + }); + const svc2 = TestBed.inject(CockpitTelemetryService); + svc2.init(); + TestBed.tick(); + await Promise.resolve(); + // Register AFTER init. + const lifecycle = makeAgentLifecycle(); + registry.register(lifecycle); + TestBed.tick(); + await Promise.resolve(); + lifecycle._setStreamStarted(); + TestBed.tick(); + await Promise.resolve(); + expect(mocks.capture).toHaveBeenCalledWith( + 'cockpit:transport_connected', + expect.anything(), + ); + }); +}); diff --git a/libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.ts b/libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.ts new file mode 100644 index 000000000..f9426f0ef --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/cockpit-telemetry.service.ts @@ -0,0 +1,125 @@ +// SPDX-License-Identifier: MIT +import { Injectable, inject, effect, untracked, Injector, runInInjectionContext } from '@angular/core'; +import posthog from 'posthog-js'; +import { COCKPIT_TELEMETRY_CONFIG } from './tokens'; +import { ActivationAggregator } from './activation-aggregator'; +import { CHAT_LIFECYCLE } from '@ngaf/chat'; +import { AgentLifecycleRegistry, type AgentLifecycle } from '@ngaf/langgraph'; +import { RENDER_LIFECYCLE } from '@ngaf/render'; +import type { CockpitEventName } from './events'; + +@Injectable() +export class CockpitTelemetryService { + private config = inject(COCKPIT_TELEMETRY_CONFIG); + private injector = inject(Injector); + private aggregator = inject(ActivationAggregator); + private initialized = false; + + init(): void { + if (this.initialized) return; + this.initialized = true; + + posthog.init(this.config.posthogKey, { + api_host: this.config.posthogHost ?? 'https://us.i.posthog.com', + persistence: 'memory', + bootstrap: { distinctID: this.config.distinctId }, + autocapture: false, + capture_pageview: false, + }); + + this.subscribeChat(); + this.subscribeAgent(); + this.subscribeRender(); + } + + private subscribeChat(): void { + const chat = this.injector.get(CHAT_LIFECYCLE, null, { optional: true }); + if (!chat) return; + let fired = false; + runInInjectionContext(this.injector, () => { + effect(() => { + if (chat.firstMessageSent() && !fired) { + fired = true; + this.capture('cockpit:chat_first_message'); + this.aggregator.markSignal('chat_first_message'); + } + }); + }); + } + + private subscribeAgent(): void { + const registry = this.injector.get(AgentLifecycleRegistry, null, { optional: true }); + if (!registry) return; + + // Track subscribed lifecycles so we don't double-subscribe on re-registration. + const subscribed = new WeakSet(); + + runInInjectionContext(this.injector, () => { + effect(() => { + const lifecycles = registry.lifecycles(); + // Creating new effects must happen outside the reactive read context; + // `untracked()` opts the effect-creation calls out of dependency + // tracking (and out of the "no effect inside reactive context" check). + untracked(() => { + for (const lifecycle of lifecycles) { + if (subscribed.has(lifecycle)) continue; + subscribed.add(lifecycle); + this.subscribeOneAgent(lifecycle); + } + }); + }); + }); + } + + private subscribeOneAgent(agent: AgentLifecycle): void { + let transportFired = false; + let threadFired = false; + let interruptFired = false; + runInInjectionContext(this.injector, () => { + effect(() => { + if (agent.streamStartedAt() !== null && !transportFired) { + transportFired = true; + this.capture('cockpit:transport_connected'); + this.aggregator.markSignal('transport_connected'); + } + }); + effect(() => { + if (agent.threadPersistedAt() !== null && !threadFired) { + threadFired = true; + this.capture('cockpit:thread_persisted'); + this.aggregator.markSignal('thread_persisted'); + } + }); + effect(() => { + if (agent.interruptResolvedAt() !== null && !interruptFired) { + interruptFired = true; + this.capture('cockpit:interrupt_handled'); + this.aggregator.markSignal('interrupt_handled'); + } + }); + }); + } + + private subscribeRender(): void { + const render = this.injector.get(RENDER_LIFECYCLE, null, { optional: true }); + if (!render) return; + let fired = false; + runInInjectionContext(this.injector, () => { + effect(() => { + if (render.firstMountAt() !== null && !fired) { + fired = true; + this.capture('cockpit:generative_component_rendered'); + this.aggregator.markSignal('generative_component_rendered'); + } + }); + }); + } + + private capture(event: CockpitEventName, properties: Record = {}): void { + try { + posthog.capture(event, { ...properties, capability: this.config.capabilitySlug }); + } catch { + // silent fail + } + } +} diff --git a/libs/cockpit-telemetry/src/lib/distinct-id.spec.ts b/libs/cockpit-telemetry/src/lib/distinct-id.spec.ts new file mode 100644 index 000000000..71e6cad06 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/distinct-id.spec.ts @@ -0,0 +1,53 @@ +// SPDX-License-Identifier: MIT +// @vitest-environment jsdom +import { describe, test, expect, beforeEach } from 'vitest'; +import { readCockpitConfigFromIframe } from './distinct-id'; + +describe('readCockpitConfigFromIframe', () => { + function setSearch(s: string): void { + Object.defineProperty(window, 'location', { + writable: true, + value: { ...window.location, search: s }, + }); + } + + beforeEach(() => setSearch('')); + + test('returns null when no URL params present', () => { + setSearch(''); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns null when cockpit_did is missing', () => { + setSearch('?cockpit_phk=k&cockpit_cap=c'); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns null when cockpit_phk is missing', () => { + setSearch('?cockpit_did=d&cockpit_cap=c'); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns null when cockpit_cap is missing', () => { + setSearch('?cockpit_did=d&cockpit_phk=k'); + expect(readCockpitConfigFromIframe()).toBe(null); + }); + + test('returns config with all params and default host', () => { + setSearch('?cockpit_did=session-1&cockpit_phk=phc_test&cockpit_cap=streaming'); + const config = readCockpitConfigFromIframe(); + expect(config).toEqual({ + distinctId: 'session-1', + posthogKey: 'phc_test', + capabilitySlug: 'streaming', + posthogHost: 'https://us.i.posthog.com', + }); + }); + + test('returns config with explicit host', () => { + setSearch( + '?cockpit_did=d&cockpit_phk=k&cockpit_cap=c&cockpit_host=https://eu.i.posthog.com', + ); + expect(readCockpitConfigFromIframe()?.posthogHost).toBe('https://eu.i.posthog.com'); + }); +}); diff --git a/libs/cockpit-telemetry/src/lib/distinct-id.ts b/libs/cockpit-telemetry/src/lib/distinct-id.ts new file mode 100644 index 000000000..6a527a460 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/distinct-id.ts @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: MIT +import type { CockpitTelemetryConfig } from './tokens'; + +/** + * Reads cockpit harness configuration from URL query parameters. + * + * The parent shell appends `cockpit_did`, `cockpit_phk`, `cockpit_cap`, and + * optionally `cockpit_host` to the iframe `src`. Returns `null` when any of + * the three required params are missing (no harness ā€” example runs pristine). + */ +export function readCockpitConfigFromIframe(): CockpitTelemetryConfig | null { + if (typeof window === 'undefined') return null; + const params = new URLSearchParams(window.location.search); + const distinctId = params.get('cockpit_did'); + const posthogKey = params.get('cockpit_phk'); + const capabilitySlug = params.get('cockpit_cap'); + if (!distinctId || !posthogKey || !capabilitySlug) return null; + return { + posthogKey, + posthogHost: params.get('cockpit_host') ?? 'https://us.i.posthog.com', + distinctId, + capabilitySlug, + }; +} diff --git a/libs/cockpit-telemetry/src/lib/events.ts b/libs/cockpit-telemetry/src/lib/events.ts new file mode 100644 index 000000000..d33ffae62 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/events.ts @@ -0,0 +1,11 @@ +// SPDX-License-Identifier: MIT +export type CockpitEventName = + | 'cockpit:recipe_opened' + | 'cockpit:mode_switched' + | 'cockpit:code_copied' + | 'cockpit:chat_first_message' + | 'cockpit:transport_connected' + | 'cockpit:thread_persisted' + | 'cockpit:interrupt_handled' + | 'cockpit:generative_component_rendered' + | 'cockpit:activation_complete'; diff --git a/libs/cockpit-telemetry/src/lib/harness.spec.ts b/libs/cockpit-telemetry/src/lib/harness.spec.ts new file mode 100644 index 000000000..346bbe855 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/harness.spec.ts @@ -0,0 +1,51 @@ +// SPDX-License-Identifier: MIT +// @vitest-environment jsdom +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { Component, type ApplicationConfig } from '@angular/core'; + +const mocks = vi.hoisted(() => ({ + bootstrapApplication: vi.fn().mockResolvedValue(undefined), +})); + +vi.mock('@angular/platform-browser', () => ({ + bootstrapApplication: mocks.bootstrapApplication, +})); + +import { bootstrapWithCockpitHarness } from './harness'; + +@Component({ selector: 'lib-test', standalone: true, template: '' }) +class TestComponent {} + +describe('bootstrapWithCockpitHarness', () => { + function setSearch(s: string): void { + Object.defineProperty(window, 'location', { + writable: true, + value: { ...window.location, search: s }, + }); + } + + beforeEach(() => { + setSearch(''); + mocks.bootstrapApplication.mockClear(); + }); + + test('bootstraps pristine when no cockpit URL params present', async () => { + setSearch(''); + const appConfig: ApplicationConfig = { providers: [] }; + await bootstrapWithCockpitHarness(TestComponent, appConfig); + expect(mocks.bootstrapApplication).toHaveBeenCalledWith( + TestComponent, + expect.objectContaining({ providers: [] }), + ); + }); + + test('bootstraps with provideCockpitTelemetry when params present', async () => { + setSearch('?cockpit_did=d1&cockpit_phk=phc_test&cockpit_cap=streaming'); + const appConfig: ApplicationConfig = { providers: [{ provide: 'TEST', useValue: 1 }] }; + await bootstrapWithCockpitHarness(TestComponent, appConfig); + const call = mocks.bootstrapApplication.mock.calls[0]; + expect(call[0]).toBe(TestComponent); + const cfg = call[1] as ApplicationConfig; + expect((cfg.providers ?? []).length).toBeGreaterThan((appConfig.providers ?? []).length); + }); +}); diff --git a/libs/cockpit-telemetry/src/lib/harness.ts b/libs/cockpit-telemetry/src/lib/harness.ts new file mode 100644 index 000000000..65528e1fd --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/harness.ts @@ -0,0 +1,25 @@ +// SPDX-License-Identifier: MIT +import { bootstrapApplication } from '@angular/platform-browser'; +import type { ApplicationConfig, Type } from '@angular/core'; +import { readCockpitConfigFromIframe } from './distinct-id'; +import { provideCockpitTelemetry } from './provide-cockpit-telemetry'; + +/** + * Entry helper for `main.cockpit.ts` of every example. + * + * When the cockpit harness URL params are present, telemetry is wired in. + * When absent, bootstraps the app pristine ā€” no telemetry providers, no + * posthog-js import side effects beyond the static module graph (which never + * pulls posthog-js because no consumer of {@link provideCockpitTelemetry} + * is in the provider tree). + */ +export async function bootstrapWithCockpitHarness( + component: Type, + appConfig: ApplicationConfig, +): Promise { + const harness = readCockpitConfigFromIframe(); + const providers = harness + ? [...(appConfig.providers ?? []), provideCockpitTelemetry(harness)] + : (appConfig.providers ?? []); + await bootstrapApplication(component, { ...appConfig, providers }); +} diff --git a/libs/cockpit-telemetry/src/lib/provide-cockpit-telemetry.ts b/libs/cockpit-telemetry/src/lib/provide-cockpit-telemetry.ts new file mode 100644 index 000000000..7588926f9 --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/provide-cockpit-telemetry.ts @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: MIT +import { + makeEnvironmentProviders, + type EnvironmentProviders, + ENVIRONMENT_INITIALIZER, + inject, +} from '@angular/core'; +import { COCKPIT_TELEMETRY_CONFIG, type CockpitTelemetryConfig } from './tokens'; +import { CockpitTelemetryService } from './cockpit-telemetry.service'; +import { ActivationAggregator } from './activation-aggregator'; +import { AgentLifecycleRegistry } from '@ngaf/langgraph'; + +export function provideCockpitTelemetry( + config: CockpitTelemetryConfig, +): EnvironmentProviders { + return makeEnvironmentProviders([ + { provide: COCKPIT_TELEMETRY_CONFIG, useValue: config }, + ActivationAggregator, + AgentLifecycleRegistry, + CockpitTelemetryService, + { + provide: ENVIRONMENT_INITIALIZER, + multi: true, + useFactory: () => { + const svc = inject(CockpitTelemetryService); + return () => svc.init(); + }, + }, + ]); +} diff --git a/libs/cockpit-telemetry/src/lib/tokens.ts b/libs/cockpit-telemetry/src/lib/tokens.ts new file mode 100644 index 000000000..5b248a2de --- /dev/null +++ b/libs/cockpit-telemetry/src/lib/tokens.ts @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: MIT +import { InjectionToken } from '@angular/core'; + +export interface CockpitTelemetryConfig { + /** PostHog project key. From URL param cockpit_phk. */ + posthogKey: string; + /** PostHog ingest host. From cockpit_host param or default. */ + posthogHost?: string; + /** Session-scoped distinct_id passed by the parent. */ + distinctId: string; + /** Capability slug (e.g. 'langgraph-streaming'). */ + capabilitySlug: string; + /** Sample rate. Default 1.0. */ + sampleRate?: number; +} + +export const COCKPIT_TELEMETRY_CONFIG = new InjectionToken( + 'COCKPIT_TELEMETRY_CONFIG', +); diff --git a/libs/cockpit-telemetry/src/public-api.ts b/libs/cockpit-telemetry/src/public-api.ts new file mode 100644 index 000000000..406ebde26 --- /dev/null +++ b/libs/cockpit-telemetry/src/public-api.ts @@ -0,0 +1,7 @@ +// SPDX-License-Identifier: MIT +export { COCKPIT_TELEMETRY_CONFIG } from './lib/tokens'; +export type { CockpitTelemetryConfig } from './lib/tokens'; +export type { CockpitEventName } from './lib/events'; +export { readCockpitConfigFromIframe } from './lib/distinct-id'; +export { provideCockpitTelemetry } from './lib/provide-cockpit-telemetry'; +export { bootstrapWithCockpitHarness } from './lib/harness'; diff --git a/libs/cockpit-telemetry/src/test-setup.ts b/libs/cockpit-telemetry/src/test-setup.ts new file mode 100644 index 000000000..054534fcf --- /dev/null +++ b/libs/cockpit-telemetry/src/test-setup.ts @@ -0,0 +1,12 @@ +// SPDX-License-Identifier: MIT +import { getTestBed } from '@angular/core/testing'; +import { + BrowserTestingModule, + platformBrowserTesting, +} from '@angular/platform-browser/testing'; + +getTestBed().initTestEnvironment( + BrowserTestingModule, + platformBrowserTesting(), + { teardown: { destroyAfterEach: true } }, +); diff --git a/libs/cockpit-telemetry/tsconfig.json b/libs/cockpit-telemetry/tsconfig.json new file mode 100644 index 000000000..a6a17f021 --- /dev/null +++ b/libs/cockpit-telemetry/tsconfig.json @@ -0,0 +1,26 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "experimentalDecorators": true, + "noPropertyAccessFromIndexSignature": true, + "module": "preserve", + "emitDeclarationOnly": false, + "composite": false + }, + "angularCompilerOptions": { + "enableI18nLegacyMessageIdFormat": false, + "strictInjectionParameters": true, + "strictInputAccessModifiers": true, + "strictTemplates": true + }, + "files": [], + "include": [], + "references": [ + { + "path": "./tsconfig.lib.json" + }, + { + "path": "./tsconfig.spec.json" + } + ] +} diff --git a/libs/cockpit-telemetry/tsconfig.lib.json b/libs/cockpit-telemetry/tsconfig.lib.json new file mode 100644 index 000000000..85e8ea120 --- /dev/null +++ b/libs/cockpit-telemetry/tsconfig.lib.json @@ -0,0 +1,13 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "../../dist/out-tsc", + "declaration": true, + "declarationMap": true, + "inlineSources": true, + "lib": ["es2022", "dom"], + "types": [] + }, + "include": ["src/**/*.ts"], + "exclude": ["src/**/*.spec.ts", "src/**/*.test.ts", "src/test-setup.ts"] +} diff --git a/libs/cockpit-telemetry/tsconfig.spec.json b/libs/cockpit-telemetry/tsconfig.spec.json new file mode 100644 index 000000000..13e304ba3 --- /dev/null +++ b/libs/cockpit-telemetry/tsconfig.spec.json @@ -0,0 +1,10 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "outDir": "../../dist/out-tsc", + "declaration": false, + "lib": ["es2022", "dom"], + "types": ["vitest/globals"] + }, + "include": ["src/**/*.ts"] +} diff --git a/libs/cockpit-telemetry/vite.config.mts b/libs/cockpit-telemetry/vite.config.mts new file mode 100644 index 000000000..1306fd366 --- /dev/null +++ b/libs/cockpit-telemetry/vite.config.mts @@ -0,0 +1,15 @@ +import { defineConfig } from 'vite'; +import angular from '@analogjs/vite-plugin-angular'; +import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin'; + +export default defineConfig({ + plugins: [angular(), nxViteTsPaths()], + test: { + globals: true, + environment: 'jsdom', + include: ['src/**/*.spec.ts'], + setupFiles: ['src/test-setup.ts'], + passWithNoTests: true, + pool: 'forks', + }, +}); diff --git a/libs/langgraph/src/lib/agent-lifecycle-registry.spec.ts b/libs/langgraph/src/lib/agent-lifecycle-registry.spec.ts new file mode 100644 index 000000000..b04b39cce --- /dev/null +++ b/libs/langgraph/src/lib/agent-lifecycle-registry.spec.ts @@ -0,0 +1,79 @@ +// SPDX-License-Identifier: MIT +// @vitest-environment jsdom +import { describe, it, expect, beforeEach } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { agent } from './agent.fn'; +import { AgentLifecycleRegistry } from './agent-lifecycle-registry'; +import { MockAgentTransport } from './transport/mock-stream.transport'; + +function withInjectionContext(fn: () => T): T { + let result!: T; + TestBed.runInInjectionContext(() => { result = fn(); }); + return result; +} + +describe('AgentLifecycleRegistry integration with agent()', () => { + beforeEach(() => { + TestBed.resetTestingModule(); + }); + + it('does not error or register when no registry is provided', () => { + TestBed.configureTestingModule({ providers: [] }); + expect(() => + withInjectionContext(() => + agent({ + assistantId: 'a', + apiUrl: 'http://localhost', + transport: new MockAgentTransport(), + threadId: null, + }), + ), + ).not.toThrow(); + }); + + it('registers the agent lifecycle when AgentLifecycleRegistry is provided', () => { + TestBed.configureTestingModule({ providers: [AgentLifecycleRegistry] }); + const registry = TestBed.inject(AgentLifecycleRegistry); + expect(registry.lifecycles()).toEqual([]); + + const a = withInjectionContext(() => + agent({ + assistantId: 'a', + apiUrl: 'http://localhost', + transport: new MockAgentTransport(), + threadId: null, + }), + ); + + const registered = registry.lifecycles(); + expect(registered.length).toBe(1); + expect(registered[0]).toBe(a.lifecycle); + }); + + it('accumulates multiple agent lifecycles in registration order', () => { + TestBed.configureTestingModule({ providers: [AgentLifecycleRegistry] }); + const registry = TestBed.inject(AgentLifecycleRegistry); + + const a1 = withInjectionContext(() => + agent({ + assistantId: 'a', + apiUrl: 'http://localhost', + transport: new MockAgentTransport(), + threadId: null, + }), + ); + const a2 = withInjectionContext(() => + agent({ + assistantId: 'b', + apiUrl: 'http://localhost', + transport: new MockAgentTransport(), + threadId: null, + }), + ); + + const registered = registry.lifecycles(); + expect(registered.length).toBe(2); + expect(registered[0]).toBe(a1.lifecycle); + expect(registered[1]).toBe(a2.lifecycle); + }); +}); diff --git a/libs/langgraph/src/lib/agent-lifecycle-registry.ts b/libs/langgraph/src/lib/agent-lifecycle-registry.ts new file mode 100644 index 000000000..ed1c87233 --- /dev/null +++ b/libs/langgraph/src/lib/agent-lifecycle-registry.ts @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT +import { Injectable, signal, type Signal } from '@angular/core'; +import type { AgentLifecycle } from './lifecycle'; + +/** + * Optional registry that collects per-instance agent lifecycles within + * an Angular injection context. External instrumentation packages + * (e.g. cockpit-telemetry) provide this token and read from it. + * + * `@ngaf/langgraph` does NOT provide this itself ā€” `agent()` writes to + * the registry only when an external consumer has provided it. + */ +@Injectable() +export class AgentLifecycleRegistry { + private readonly _lifecycles = signal([]); + + /** Reactive list of registered lifecycles. */ + readonly lifecycles: Signal = this._lifecycles.asReadonly(); + + register(lifecycle: AgentLifecycle): void { + this._lifecycles.update((curr) => [...curr, lifecycle]); + } +} diff --git a/libs/langgraph/src/lib/agent.fn.ts b/libs/langgraph/src/lib/agent.fn.ts index 0936b0eb6..3c1fdfaff 100644 --- a/libs/langgraph/src/lib/agent.fn.ts +++ b/libs/langgraph/src/lib/agent.fn.ts @@ -1,9 +1,11 @@ // SPDX-License-Identifier: MIT import { inject, DestroyRef, computed, effect, - isSignal, Signal, + isSignal, signal, Signal, } from '@angular/core'; import { AGENT_CONFIG } from './agent.provider'; +import type { AgentLifecycle } from './lifecycle'; +import { AgentLifecycleRegistry } from './agent-lifecycle-registry'; import { toSignal, toObservable } from '@angular/core/rxjs-interop'; import { BehaviorSubject, Subject, of, @@ -197,6 +199,86 @@ export function agent< lastThreadId = id; }); + // ā”€ā”€ Lifecycle instrumentation ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ + // Eight signals tracking key transitions for telemetry/observability. + // All reset together via resetLifecycle(); see switchThread() below. + const lcStreamStartedAt = signal(null); + const lcStreamErrorAt = signal<{ at: number; classification: string } | null>(null); + const lcInterruptReceivedAt = signal(null); + const lcInterruptResolvedAt = signal(null); + const lcThreadCreatedAt = signal(null); + const lcThreadPersistedAt = signal(null); + const lcToolCallStartedAt = signal(null); + const lcToolCallCompletedAt = signal(null); + + const lifecycle: AgentLifecycle = { + streamStartedAt: lcStreamStartedAt, + streamErrorAt: lcStreamErrorAt, + interruptReceivedAt: lcInterruptReceivedAt, + interruptResolvedAt: lcInterruptResolvedAt, + threadCreatedAt: lcThreadCreatedAt, + threadPersistedAt: lcThreadPersistedAt, + toolCallStartedAt: lcToolCallStartedAt, + toolCallCompletedAt: lcToolCallCompletedAt, + }; + + // Register with optional lifecycle registry. External instrumentation + // (e.g. cockpit-telemetry) provides AgentLifecycleRegistry to receive + // per-agent lifecycles created within this injection context. + const lifecycleRegistry = inject(AgentLifecycleRegistry, { optional: true }); + lifecycleRegistry?.register(lifecycle); + + function resetLifecycle(): void { + lcStreamStartedAt.set(null); + lcStreamErrorAt.set(null); + lcInterruptReceivedAt.set(null); + lcInterruptResolvedAt.set(null); + lcThreadCreatedAt.set(null); + lcThreadPersistedAt.set(null); + lcToolCallStartedAt.set(null); + lcToolCallCompletedAt.set(null); + } + + // First chunk: first values$ or messages$ emission with content. + values$.pipe(takeUntil(destroy$)).subscribe(v => { + if (lcStreamStartedAt() === null && v != null && Object.keys(v as object).length > 0) { + lcStreamStartedAt.set(Date.now()); + } + }); + messages$.pipe(takeUntil(destroy$)).subscribe(m => { + if (lcStreamStartedAt() === null && m.length > 0) lcStreamStartedAt.set(Date.now()); + }); + // Stream error: capture timestamp + classification (Error name or 'unknown'). + error$.pipe(takeUntil(destroy$)).subscribe(e => { + if (e == null) return; + const classification = e instanceof Error ? e.name : typeof e === 'string' ? 'string' : 'unknown'; + lcStreamErrorAt.set({ at: Date.now(), classification }); + }); + // First non-null interrupt within this thread. + interrupt$.pipe(takeUntil(destroy$)).subscribe(ix => { + if (ix != null && lcInterruptReceivedAt() === null) lcInterruptReceivedAt.set(Date.now()); + }); + // First tool call append; first completed/error result transition. + const seenToolCallStates = new Map(); + toolCalls$.pipe(takeUntil(destroy$)).subscribe(tcs => { + if (tcs.length > 0 && lcToolCallStartedAt() === null) lcToolCallStartedAt.set(Date.now()); + if (lcToolCallCompletedAt() !== null) return; + for (const tc of tcs) { + const prev = seenToolCallStates.get(tc.id); + if (prev !== tc.state && (tc.state === 'completed' || tc.state === 'error')) { + lcToolCallCompletedAt.set(Date.now()); + seenToolCallStates.set(tc.id, tc.state); + break; + } + seenToolCallStates.set(tc.id, tc.state); + } + }); + // Thread restored from server: history$ populates with content for a + // pre-existing threadId. + history$.pipe(takeUntil(destroy$)).subscribe(h => { + if (h.length > 0 && lcThreadPersistedAt() === null) lcThreadPersistedAt.set(Date.now()); + }); + const manager = createStreamManagerBridge({ options: { ...options, apiUrl, transport }, subjects, @@ -299,6 +381,14 @@ export function agent< history: historyNeutral, messageCheckpoints: messageCheckpointsSig, submit: (input: AgentSubmitInput | null | undefined, opts?: AgentSubmitOptions & LangGraphSubmitOptions) => { + // Lifecycle: first submit with no existing threadId ā†’ thread create. + if (lcThreadCreatedAt() === null && lastThreadId == null) { + lcThreadCreatedAt.set(Date.now()); + } + // Lifecycle: any resume submit marks an interrupt resolution. + if (input?.resume !== undefined || opts?.resume !== undefined) { + lcInterruptResolvedAt.set(Date.now()); + } const request = buildSubmitRequest(input, opts); return manager.submit(request.payload, request.options); }, @@ -400,8 +490,11 @@ export function agent< isThreadLoading: threadLoadSig, switchThread: (id) => { resetDerivedThreadState(); + resetLifecycle(); + seenToolCallStates.clear(); manager.switchThread(id); }, + lifecycle, joinStream: (id, last) => manager.joinStream(id, last), getMessagesMetadata: (msg, idx) => { const id = (msg as unknown as Record)['id']; diff --git a/libs/langgraph/src/lib/agent.types.ts b/libs/langgraph/src/lib/agent.types.ts index c45a605f8..c9f658bad 100644 --- a/libs/langgraph/src/lib/agent.types.ts +++ b/libs/langgraph/src/lib/agent.types.ts @@ -21,6 +21,7 @@ import type { } from '@langchain/langgraph-sdk/ui'; import type { BaseMessage, AIMessage as CoreAIMessage } from '@langchain/core/messages'; import type { AgentSubmitInput, AgentSubmitOptions, AgentWithHistory } from '@ngaf/chat'; +import type { AgentLifecycle } from './lifecycle'; // Re-export SDK types so consumers don't need to import from langgraph-sdk directly export type { BagTemplate, InferBag, Interrupt, ThreadState, SubmitOptions }; @@ -371,6 +372,14 @@ export interface LangGraphAgent ToolCallWithResult[]; + + /** + * Lifecycle signals for observability/telemetry. Eight read-only signals + * capture key transitions (first stream chunk, first interrupt, tool + * call start/complete, thread create/persist, errors). All reset on + * `switchThread()`. See {@link AgentLifecycle}. + */ + lifecycle: AgentLifecycle; } // ā”€ā”€ Internal: StreamSubjects ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ diff --git a/libs/langgraph/src/lib/lifecycle.spec.ts b/libs/langgraph/src/lib/lifecycle.spec.ts new file mode 100644 index 000000000..d1d607529 --- /dev/null +++ b/libs/langgraph/src/lib/lifecycle.spec.ts @@ -0,0 +1,196 @@ +// @vitest-environment jsdom +// SPDX-License-Identifier: MIT +import { describe, it, expect, beforeEach } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { agent } from './agent.fn'; +import { MockAgentTransport } from './transport/mock-stream.transport'; +import type { ThreadState } from '@langchain/langgraph-sdk'; + +function withInjectionContext(fn: () => T): T { + let result!: T; + TestBed.runInInjectionContext(() => { result = fn(); }); + return result; +} + +function tick(ms = 30): Promise { + return new Promise(r => setTimeout(r, ms)); +} + +function threadState(checkpointId: string): ThreadState> { + return { + values: { messages: [] }, + next: [], + checkpoint: { + thread_id: 'thread-1', + checkpoint_ns: '', + checkpoint_id: checkpointId, + checkpoint_map: null, + }, + metadata: null, + created_at: '2026-05-02T00:00:00.000Z', + parent_checkpoint: null, + tasks: [], + }; +} + +describe('AGENT_LIFECYCLE', () => { + beforeEach(() => TestBed.configureTestingModule({})); + + it('streamStartedAt is null before any stream', () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport }), + ); + expect(ref.lifecycle.streamStartedAt()).toBeNull(); + }); + + it('streamStartedAt fires on first stream chunk', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport }), + ); + ref.submit({ message: 'hi' }); + transport.emit([{ type: 'values', values: { x: 1 } }]); + transport.close(); + await tick(); + const at = ref.lifecycle.streamStartedAt(); + expect(at).not.toBeNull(); + expect(typeof at).toBe('number'); + }); + + it('interruptReceivedAt fires when interrupt$ becomes non-null', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport }), + ); + ref.submit({ message: 'hi' }); + transport.emit([ + { + type: 'values', + values: { __interrupt__: [{ id: 'i-1', value: { question: 'ok?' } }] }, + }, + ]); + transport.close(); + await tick(); + expect(ref.lifecycle.interruptReceivedAt()).not.toBeNull(); + }); + + it('interruptResolvedAt fires on submit({ resume })', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport, threadId: 'thread-1' }), + ); + expect(ref.lifecycle.interruptResolvedAt()).toBeNull(); + void ref.submit({ resume: { approved: true } }); + await tick(10); + expect(ref.lifecycle.interruptResolvedAt()).not.toBeNull(); + }); + + it('threadCreatedAt fires on first submit with no existing threadId', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport }), + ); + expect(ref.lifecycle.threadCreatedAt()).toBeNull(); + void ref.submit({ message: 'first' }); + await tick(10); + expect(ref.lifecycle.threadCreatedAt()).not.toBeNull(); + }); + + it('threadPersistedAt fires when agent restores from existing threadId', async () => { + const transport = new MockAgentTransport(); + transport.history = [threadState('cp-1')]; + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport, threadId: 'thread-1' }), + ); + await tick(30); + expect(ref.lifecycle.threadPersistedAt()).not.toBeNull(); + }); + + it('toolCallStartedAt fires on first tool call append', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport }), + ); + ref.submit({ message: 'hi' }); + transport.emit([{ + type: 'messages', + messages: [{ + id: 'ai-1', + type: 'ai', + content: '', + tool_calls: [{ id: 'tc-1', name: 'search', args: {} }], + }], + }]); + transport.close(); + await tick(); + expect(ref.lifecycle.toolCallStartedAt()).not.toBeNull(); + }); + + it('toolCallCompletedAt fires on tool call result transition', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport, throttle: false }), + ); + ref.submit({ message: 'hi' }); + transport.emit([{ + type: 'messages', + messages: [ + { + id: 'ai-1', + type: 'ai', + content: '', + tool_calls: [{ id: 'tc-1', name: 'search', args: {} }], + }, + { + id: 'tool-1', + type: 'tool', + tool_call_id: 'tc-1', + content: 'done', + status: 'success', + }, + ], + }]); + transport.close(); + await tick(30); + expect(ref.lifecycle.toolCallCompletedAt()).not.toBeNull(); + }); + + it('streamErrorAt fires when transport errors', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport }), + ); + ref.submit({ message: 'hi' }); + transport.emitError(new Error('boom')); + await tick(); + const err = ref.lifecycle.streamErrorAt(); + expect(err).not.toBeNull(); + expect(err!.at).toBeGreaterThan(0); + expect(typeof err!.classification).toBe('string'); + }); + + it('all signals reset to null on switchThread(null)', async () => { + const transport = new MockAgentTransport(); + const ref = withInjectionContext(() => + agent({ apiUrl: '', assistantId: 'a', transport }), + ); + ref.submit({ message: 'hi' }); + transport.emit([{ type: 'values', values: { x: 1 } }]); + transport.emitError(new Error('boom')); + await tick(); + expect(ref.lifecycle.streamStartedAt()).not.toBeNull(); + expect(ref.lifecycle.streamErrorAt()).not.toBeNull(); + + ref.switchThread(null); + await tick(10); + expect(ref.lifecycle.streamStartedAt()).toBeNull(); + expect(ref.lifecycle.streamErrorAt()).toBeNull(); + expect(ref.lifecycle.interruptReceivedAt()).toBeNull(); + expect(ref.lifecycle.interruptResolvedAt()).toBeNull(); + expect(ref.lifecycle.threadCreatedAt()).toBeNull(); + expect(ref.lifecycle.threadPersistedAt()).toBeNull(); + expect(ref.lifecycle.toolCallStartedAt()).toBeNull(); + expect(ref.lifecycle.toolCallCompletedAt()).toBeNull(); + }); +}); diff --git a/libs/langgraph/src/lib/lifecycle.ts b/libs/langgraph/src/lib/lifecycle.ts new file mode 100644 index 000000000..0b5a6c1a7 --- /dev/null +++ b/libs/langgraph/src/lib/lifecycle.ts @@ -0,0 +1,23 @@ +// SPDX-License-Identifier: MIT +import { InjectionToken, Signal } from '@angular/core'; + +export interface AgentLifecycle { + /** Epoch ms of the first stream chunk arrival. Resets on clearThread. */ + readonly streamStartedAt: Signal; + /** Epoch ms + classification of the most recent stream error. Resets on clearThread. */ + readonly streamErrorAt: Signal<{ at: number; classification: string } | null>; + /** Epoch ms of the first interrupt$ non-null in this stream. Resets on clearThread. */ + readonly interruptReceivedAt: Signal; + /** Epoch ms of the most recent submit({ interrupt }) call. Resets on clearThread. */ + readonly interruptResolvedAt: Signal; + /** Epoch ms when the agent's "create new thread" branch fired. Resets on clearThread. */ + readonly threadCreatedAt: Signal; + /** Epoch ms when an existing thread was restored from server (proves persistence). Resets on clearThread. */ + readonly threadPersistedAt: Signal; + /** Epoch ms of the first tool call append. Resets on clearThread. */ + readonly toolCallStartedAt: Signal; + /** Epoch ms of the first tool call result transition. Resets on clearThread. */ + readonly toolCallCompletedAt: Signal; +} + +export const AGENT_LIFECYCLE = new InjectionToken('AGENT_LIFECYCLE'); diff --git a/libs/langgraph/src/lib/testing/mock-langgraph-agent.ts b/libs/langgraph/src/lib/testing/mock-langgraph-agent.ts index 1f7b8c411..bbba103bb 100644 --- a/libs/langgraph/src/lib/testing/mock-langgraph-agent.ts +++ b/libs/langgraph/src/lib/testing/mock-langgraph-agent.ts @@ -160,6 +160,16 @@ export function mockLangGraphAgent( joinStream: (_runId: string, _lastEventId?: string) => Promise.resolve(), getMessagesMetadata: (_msg: BaseMessage, _idx?: number): MessageMetadata> | undefined => undefined, getToolCalls: (_msg: CoreAIMessage): ToolCallWithResult[] => [], + lifecycle: { + streamStartedAt: signal(null), + streamErrorAt: signal<{ at: number; classification: string } | null>(null), + interruptReceivedAt: signal(null), + interruptResolvedAt: signal(null), + threadCreatedAt: signal(null), + threadPersistedAt: signal(null), + toolCallStartedAt: signal(null), + toolCallCompletedAt: signal(null), + }, }; return mock; diff --git a/libs/langgraph/src/public-api.ts b/libs/langgraph/src/public-api.ts index 3e473f9e5..a7d24c066 100644 --- a/libs/langgraph/src/public-api.ts +++ b/libs/langgraph/src/public-api.ts @@ -6,6 +6,11 @@ export { agent } from './lib/agent.fn'; export { provideAgent, AGENT_CONFIG } from './lib/agent.provider'; export type { AgentConfig } from './lib/agent.provider'; +// Lifecycle monitoring +export { AGENT_LIFECYCLE } from './lib/lifecycle'; +export type { AgentLifecycle } from './lib/lifecycle'; +export { AgentLifecycleRegistry } from './lib/agent-lifecycle-registry'; + // Public types export type { AgentOptions, diff --git a/libs/render/src/lib/lifecycle.spec.ts b/libs/render/src/lib/lifecycle.spec.ts new file mode 100644 index 000000000..48d576cf5 --- /dev/null +++ b/libs/render/src/lib/lifecycle.spec.ts @@ -0,0 +1,55 @@ +// SPDX-License-Identifier: MIT +// @vitest-environment jsdom +import { describe, test, expect, beforeEach, vi } from 'vitest'; +import { TestBed } from '@angular/core/testing'; +import { RenderLifecycleService } from './render-lifecycle.service'; +import { RENDER_LIFECYCLE } from './lifecycle'; +import { provideRender } from './provide-render'; +import { + __resetRunLicenseCheckStateForTests, + __resetNagStateForTests, +} from '@ngaf/licensing/testing'; + +describe('RenderLifecycle', () => { + let service: RenderLifecycleService; + + beforeEach(() => { + __resetRunLicenseCheckStateForTests(); + __resetNagStateForTests(); + globalThis.console.warn = vi.fn(); + TestBed.configureTestingModule({ + providers: [provideRender({})], + }); + service = TestBed.inject(RENDER_LIFECYCLE) as RenderLifecycleService; + }); + + test('firstMountAt is null before any mount', () => { + expect(service.firstMountAt()).toBe(null); + }); + + test('firstMountAt captures the first mount and stays sticky', () => { + service.notifyLifecycle({ kind: 'element', type: 'mounted', elementType: 'button' }); + const first = service.firstMountAt(); + expect(first?.elementType).toBe('button'); + service.notifyLifecycle({ kind: 'element', type: 'mounted', elementType: 'card' }); + expect(service.firstMountAt()?.elementType).toBe('button'); + }); + + test('mountCount increments on each mount', () => { + service.notifyLifecycle({ kind: 'element', type: 'mounted' }); + service.notifyLifecycle({ kind: 'element', type: 'mounted' }); + service.notifyLifecycle({ kind: 'spec', type: 'mounted' }); + expect(service.mountCount()).toBe(3); + }); + + test('lastStateChangeAt updates on state change notifications', () => { + expect(service.lastStateChangeAt()).toBe(null); + service.notifyStateChange(); + expect(service.lastStateChangeAt()).toBeGreaterThan(0); + }); + + test('lastHandlerInvokedAt updates with action name and timestamp', () => { + service.notifyHandlerInvoked('save'); + expect(service.lastHandlerInvokedAt()?.action).toBe('save'); + }); +}); diff --git a/libs/render/src/lib/lifecycle.ts b/libs/render/src/lib/lifecycle.ts new file mode 100644 index 000000000..18a4f585b --- /dev/null +++ b/libs/render/src/lib/lifecycle.ts @@ -0,0 +1,17 @@ +// SPDX-License-Identifier: MIT +import { InjectionToken, Signal } from '@angular/core'; + +export interface RenderLifecycle { + /** First mount event in this render context. Sticky ā€” does not reset. */ + readonly firstMountAt: Signal<{ kind: 'spec' | 'element'; elementType?: string; at: number } | null>; + /** Total mount count since render context started. */ + readonly mountCount: Signal; + /** Epoch ms of the most recent mount event. */ + readonly lastMountAt: Signal; + /** Epoch ms of the most recent state-change event. */ + readonly lastStateChangeAt: Signal; + /** Most recent handler invocation. */ + readonly lastHandlerInvokedAt: Signal<{ action: string; at: number } | null>; +} + +export const RENDER_LIFECYCLE = new InjectionToken('RENDER_LIFECYCLE'); diff --git a/libs/render/src/lib/provide-render.ts b/libs/render/src/lib/provide-render.ts index 8dd0f255a..af2146bf4 100644 --- a/libs/render/src/lib/provide-render.ts +++ b/libs/render/src/lib/provide-render.ts @@ -6,6 +6,8 @@ import { inferNoncommercial, } from '@ngaf/licensing'; import type { RenderConfig } from './render.types'; +import { RENDER_LIFECYCLE } from './lifecycle'; +import { RenderLifecycleService } from './render-lifecycle.service'; const PACKAGE_NAME = '@ngaf/render'; declare const __CACHEPLANE_RENDER_VERSION__: string | undefined; @@ -30,5 +32,7 @@ export function provideRender(config: RenderConfig) { return makeEnvironmentProviders([ { provide: RENDER_CONFIG, useValue: config }, + RenderLifecycleService, + { provide: RENDER_LIFECYCLE, useExisting: RenderLifecycleService }, ]); } diff --git a/libs/render/src/lib/render-lifecycle.service.ts b/libs/render/src/lib/render-lifecycle.service.ts new file mode 100644 index 000000000..a7a9881cc --- /dev/null +++ b/libs/render/src/lib/render-lifecycle.service.ts @@ -0,0 +1,42 @@ +// SPDX-License-Identifier: MIT +import { Injectable, signal } from '@angular/core'; +import type { RenderLifecycle } from './lifecycle'; + +/** + * Provided by `provideRender()` ā€” opt-in. Scope follows the consumer's + * `provideRender` call (root-scoped by default, sub-tree if `provideRender` + * is in a sub-injector). + */ +@Injectable() +export class RenderLifecycleService implements RenderLifecycle { + private _firstMountAt = signal<{ kind: 'spec' | 'element'; elementType?: string; at: number } | null>(null); + private _mountCount = signal(0); + private _lastMountAt = signal(null); + private _lastStateChangeAt = signal(null); + private _lastHandlerInvokedAt = signal<{ action: string; at: number } | null>(null); + + readonly firstMountAt = this._firstMountAt.asReadonly(); + readonly mountCount = this._mountCount.asReadonly(); + readonly lastMountAt = this._lastMountAt.asReadonly(); + readonly lastStateChangeAt = this._lastStateChangeAt.asReadonly(); + readonly lastHandlerInvokedAt = this._lastHandlerInvokedAt.asReadonly(); + + notifyLifecycle(event: { kind: 'spec' | 'element'; type: 'mounted' | 'destroyed'; elementType?: string }): void { + if (event.type === 'mounted') { + const now = Date.now(); + if (this._firstMountAt() === null) { + this._firstMountAt.set({ kind: event.kind, elementType: event.elementType, at: now }); + } + this._mountCount.update((c) => c + 1); + this._lastMountAt.set(now); + } + } + + notifyStateChange(): void { + this._lastStateChangeAt.set(Date.now()); + } + + notifyHandlerInvoked(action: string): void { + this._lastHandlerInvokedAt.set({ action, at: Date.now() }); + } +} diff --git a/libs/render/src/lib/render-spec.component.ts b/libs/render/src/lib/render-spec.component.ts index cac8accfc..dd249c87a 100644 --- a/libs/render/src/lib/render-spec.component.ts +++ b/libs/render/src/lib/render-spec.component.ts @@ -19,6 +19,7 @@ import type { RenderContext } from './contexts/render-context'; import type { AngularRegistry } from './render.types'; import { signalStateStore } from './signal-state-store'; import type { RenderEvent } from './render-event'; +import { RenderLifecycleService } from './render-lifecycle.service'; /** * Top-level entry point for rendering a json-render spec. @@ -63,6 +64,7 @@ export class RenderSpecComponent implements OnInit { private readonly config = inject(RENDER_CONFIG, { optional: true }); private readonly destroyRef = inject(DestroyRef); + private readonly lifecycle = inject(RenderLifecycleService, { optional: true }); /** Internal store, lazily created once and reused across spec changes. */ private _internalStore: StateStore | undefined; @@ -104,14 +106,14 @@ export class RenderSpecComponent implements OnInit { if (result instanceof Promise) { result.then( (r) => { - this.events.emit({ type: 'handler', action: name, params, result: r }); + this.emitTapped({ type: 'handler', action: name, params, result: r }); }, () => { - this.events.emit({ type: 'handler', action: name, params, result: undefined }); + this.emitTapped({ type: 'handler', action: name, params, result: undefined }); }, ); } else { - this.events.emit({ type: 'handler', action: name, params, result }); + this.emitTapped({ type: 'handler', action: name, params, result }); } return result; }; @@ -119,9 +121,31 @@ export class RenderSpecComponent implements OnInit { return wrapped; }); + /** Emits a RenderEvent through the events output and notifies the + * lifecycle service (single tap point ā€” all events flow through here). */ + private readonly emitTapped = (event: RenderEvent): void => { + this.events.emit(event); + if (!this.lifecycle) return; + switch (event.type) { + case 'lifecycle': + this.lifecycle.notifyLifecycle({ + kind: event.scope, + type: event.event, + elementType: event.elementType, + }); + break; + case 'stateChange': + this.lifecycle.notifyStateChange(); + break; + case 'handler': + this.lifecycle.notifyHandlerInvoked(event.action); + break; + } + }; + /** Emits a RenderEvent through the events output. */ private readonly emitEvent = (event: RenderEvent) => { - this.events.emit(event); + this.emitTapped(event); }; /** The RenderContext provided to children via viewProviders. */ @@ -140,7 +164,7 @@ export class RenderSpecComponent implements OnInit { const store = this.resolvedStore(); const unsub = store.subscribe(() => { const snapshot = store.getSnapshot() as Record; - this.events.emit({ + this.emitTapped({ type: 'stateChange', path: '/', value: snapshot, @@ -151,11 +175,11 @@ export class RenderSpecComponent implements OnInit { }); this.destroyRef.onDestroy(() => { - this.events.emit({ type: 'lifecycle', event: 'destroyed', scope: 'spec' }); + this.emitTapped({ type: 'lifecycle', event: 'destroyed', scope: 'spec' }); }); } ngOnInit(): void { - this.events.emit({ type: 'lifecycle', event: 'mounted', scope: 'spec' }); + this.emitTapped({ type: 'lifecycle', event: 'mounted', scope: 'spec' }); } } diff --git a/libs/render/src/public-api.ts b/libs/render/src/public-api.ts index a02ad70b2..44fd43c7b 100644 --- a/libs/render/src/public-api.ts +++ b/libs/render/src/public-api.ts @@ -40,6 +40,10 @@ export type { RenderLifecycleEvent, } from './lib/render-event'; +// Lifecycle +export { RENDER_LIFECYCLE } from './lib/lifecycle'; +export type { RenderLifecycle } from './lib/lifecycle'; + // Fallback export { DefaultFallbackComponent } from './lib/default-fallback.component'; export type { RenderViewEntry } from './lib/render.types'; diff --git a/package-lock.json b/package-lock.json index d479afbc8..fe59d3e6a 100644 --- a/package-lock.json +++ b/package-lock.json @@ -223,6 +223,59 @@ "version": "0.0.29", "license": "MIT" }, + "libs/cockpit-telemetry": { + "name": "@ngaf/cockpit-telemetry", + "version": "0.0.0", + "license": "MIT", + "dependencies": { + "posthog-js": "^1.373.0" + }, + "peerDependencies": { + "@angular/core": "^20.0.0 || ^21.0.0" + } + }, + "libs/cockpit-telemetry/node_modules/@posthog/core": { + "version": "1.29.2", + "resolved": "https://registry.npmjs.org/@posthog/core/-/core-1.29.2.tgz", + "integrity": "sha512-DYhR0Sl7pVdUXa+C9poCVjTj3D6SI9P7RLhIhr74YyHeHuCGL/MZsDEWcz3ul3qHDIhZU9myIUjID890QiQw+g==", + "license": "MIT", + "dependencies": { + "@posthog/types": "1.373.5" + } + }, + "libs/cockpit-telemetry/node_modules/@posthog/types": { + "version": "1.373.5", + "resolved": "https://registry.npmjs.org/@posthog/types/-/types-1.373.5.tgz", + "integrity": "sha512-K7STCnRG/WBE1q0BwEkIcrJB5OqECaymsQj6Hp4Ntvaek4dqHkZGfp6hxwIPqQPjlOXwidwPLo+XGsn+CoZUyw==", + "license": "MIT" + }, + "libs/cockpit-telemetry/node_modules/fflate": { + "version": "0.4.8", + "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.4.8.tgz", + "integrity": "sha512-FJqqoDBR00Mdj9ppamLa/Y7vxm+PRmNWA67N846RvsoYVMKB4q3y/de5PA7gUmRMYK/8CMz2GDZQmCRN1wBcWA==", + "license": "MIT" + }, + "libs/cockpit-telemetry/node_modules/posthog-js": { + "version": "1.373.5", + "resolved": "https://registry.npmjs.org/posthog-js/-/posthog-js-1.373.5.tgz", + "integrity": "sha512-VjeSKiAtbRxcKXr+lFWlHNd9GGxA3A1gZ87EsIZmEV3N8SwO11uAf6JDTEuymdUNGn99XTvWcPrBCxkSBgVAEg==", + "license": "SEE LICENSE IN LICENSE", + "dependencies": { + "@opentelemetry/api": "^1.9.0", + "@opentelemetry/api-logs": "^0.208.0", + "@opentelemetry/exporter-logs-otlp-http": "^0.208.0", + "@opentelemetry/resources": "^2.2.0", + "@opentelemetry/sdk-logs": "^0.208.0", + "@posthog/core": "1.29.2", + "@posthog/types": "1.373.5", + "core-js": "^3.38.1", + "dompurify": "^3.3.2", + "fflate": "^0.4.8", + "preact": "^10.28.2", + "query-selector-shadow-dom": "^1.0.1", + "web-vitals": "^5.1.0" + } + }, "libs/cockpit-testing": { "name": "@ngaf/cockpit-testing", "version": "0.0.29", @@ -11985,6 +12038,10 @@ "resolved": "libs/cockpit-shell", "link": true }, + "node_modules/@ngaf/cockpit-telemetry": { + "resolved": "libs/cockpit-telemetry", + "link": true + }, "node_modules/@ngaf/cockpit-testing": { "resolved": "libs/cockpit-testing", "link": true diff --git a/tools/posthog/dashboards/developer-funnel.json b/tools/posthog/dashboards/developer-funnel.json index 96d0ef496..34db728cc 100644 --- a/tools/posthog/dashboards/developer-funnel.json +++ b/tools/posthog/dashboards/developer-funnel.json @@ -19,7 +19,7 @@ "insight": "cockpit-recipe-completion" }, { - "insight": "six-signal-activation-funnel" + "insight": "activation-funnel" } ] } diff --git a/tools/posthog/insights/six-signal-activation-funnel.json b/tools/posthog/insights/activation-funnel.json similarity index 69% rename from tools/posthog/insights/six-signal-activation-funnel.json rename to tools/posthog/insights/activation-funnel.json index 435e782f8..a26cd081a 100644 --- a/tools/posthog/insights/six-signal-activation-funnel.json +++ b/tools/posthog/insights/activation-funnel.json @@ -1,20 +1,17 @@ { - "slug": "six-signal-activation-funnel", - "posthog_id": 8587351, + "slug": "activation-funnel", + "posthog_id": null, "kind": "funnel", - "name": "Six-signal activation (30-min window)", + "name": "Activation funnel (30-min window)", "interval": "day", "window_minutes": 30, "steps": [ { - "event": "cockpit:install_command_copied" + "event": "cockpit:chat_first_message" }, { "event": "cockpit:transport_connected" }, - { - "event": "cockpit:chat_first_message" - }, { "event": "cockpit:thread_persisted" }, diff --git a/tools/posthog/insights/cockpit-recipe-completion.json b/tools/posthog/insights/cockpit-recipe-completion.json index 2b7bedd0e..3d2cb2219 100644 --- a/tools/posthog/insights/cockpit-recipe-completion.json +++ b/tools/posthog/insights/cockpit-recipe-completion.json @@ -5,7 +5,7 @@ "name": "Cockpit recipe completion", "events": [ { - "event": "cockpit:recipe_start", + "event": "cockpit:recipe_opened", "math": "total" }, { diff --git a/tsconfig.base.json b/tsconfig.base.json index 79183d553..83322225f 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -26,6 +26,7 @@ ], "@ngaf/cockpit-registry": ["libs/cockpit-registry/src/index.ts"], "@ngaf/cockpit-shell": ["libs/cockpit-shell/src/index.ts"], + "@ngaf/cockpit-telemetry": ["libs/cockpit-telemetry/src/index.ts"], "@ngaf/cockpit-testing": ["libs/cockpit-testing/src/index.ts"], "@ngaf/cockpit-ui": ["libs/cockpit-ui/src/index.ts"], "@ngaf/db": ["libs/db/src/index.ts"],