The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat: implement privacy-preserving usage analytics collection and reporting system
0xken1534626b1ca12f
diff --git a/cli/src/cli.ts b/cli/src/cli.tsindex 7bbadb838..8948d1664 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -44,6 +44,8 @@ import { Watcher, type LineEvent } from './watcher/watcher.js'import { startHookServer } from './hookServer.js'import { BackendSocket } from './backendSocket.js'import { lastTurnTextFromRawLines, lineToEvents, newTurnState, type LiveEvent, type TurnState } from './lib/normalize.js'+import { AnalyticsCollector } from './lib/analytics/collector.js'+import { runAnalyticsCommand } from './lib/analytics/command.js'import { AskQuestionController, pollsQuestions, QuestionWatcher } from './lib/askQuestion.js'import { CommanderMirror } from './lib/commander.js'import {@@ -512,6 +514,20 @@ async function runForeground(token: string): Promise<void> {const devinReaders = new Map<string, DevinReader>()const commandcodeNormalizers = new Map<string, CommandCodeNormalizer>()const watcher = new Watcher()+ /**+ * Harness Analytics (autonomous-code docs/design/harness-analytics.md).+ *+ * Collection starts now; NOTHING is uploaded until the account owner has acknowledged the field+ * list — the backend answers `consent: "unacknowledged"` until then and the snapshot simply waits.+ * That hold is what lets the CLI be on by default while running headless, where there is no screen+ * to show a preview on.+ */+ const analytics = new AnalyticsCollector({+ token: () => readSavedToken(),+ enginesPresent: () => [...new Set(registry.list().map((entry) => entry.engine))],+ collectorVersion: VERSION,+ })+ analytics.start()const queuedSessionEvents: Array<{sessionId: stringevents: ReturnType<CursorNormalizer['ingest']>@@ -931,6 +947,14 @@ async function runForeground(token: string): Promise<void> {backend.send({ ...event, dbSessionId: sessionId })if (event.type === 'turn_started') {turnStartedAt.set(sessionId, Date.now())+ // Analytics: count HERE, inside the one funnel every engine's normalizer feeds and BEFORE+ // backend.send seals the frame. The relay only ever sees ciphertext, so this is the only+ // layer that can tell a real instruction from a duplicated control frame.+ analytics.sessionTurnStarted(+ sessionId,+ registry.bySession(sessionId)?.engine ?? 'claude',+ agentIdFor(sessionId),+ )console.log(`[turn] ${sid(sessionId)} started · engine=${registry.bySession(sessionId)?.engine ?? 'claude'} · "${preview(event.payload.userMessage)}"`)input.onTurnStarted(agentIdFor(sessionId), event.payload.userMessage)startHeartbeat(sessionId)@@ -938,6 +962,7 @@ async function runForeground(token: string): Promise<void> {} else if (event.type === 'turn_ended') {const startedAt = turnStartedAt.get(sessionId)turnStartedAt.delete(sessionId)+ analytics.sessionTurnEnded(sessionId, event.payload.aborted === true)// Say when a turn was KILLED. The log previously showed an interrupt as a fresh `[turn] started// "[Request interrupted by user]"`, which read like a new prompt and hid the bug for weeks.console.log(@@ -992,6 +1017,7 @@ async function runForeground(token: string): Promise<void> {syncRecapPool()turnStates.delete(sessionId)turnStartedAt.delete(sessionId)+ analytics.sessionClosed(sessionId) // an open turn here died with the session; count it as failedcodexNormalizers.delete(sessionId)cursorNormalizers.delete(sessionId)opencodeReaders.get(sessionId)?.stop()@@ -2247,6 +2273,12 @@ switch (cmd) {case 'reset':resetCommand().catch(onError)break+ case 'analytics':+ // Local half of the consent contract: see exactly what would leave this computer, and stop it.+ // Runs without the daemon — it reads the persisted snapshot, so it works on a computer that has+ // never uploaded anything.+ console.log(runAnalyticsCommand(process.argv[3]))+ breakcase 'status':status().catch(onError)breakdiff --git a/cli/src/config/env.ts b/cli/src/config/env.tsindex d9b265483..1a126cb59 100644--- a/cli/src/config/env.ts+++ b/cli/src/config/env.ts@@ -168,6 +168,15 @@ const envSchema = z.object({DEVIN_CONFIG_PATH: z.string().default(join(homedir(), '.config', 'devin', 'config.json')),// Where the tmux-session registry + connect token are persisted.ADAPTER_DATA_DIR: z.string().default(adapterDataDir),+ // ---- Harness Analytics (see autonomous-code docs/design/harness-analytics.md) ----+ // Collection is ON by default, but this computer uploads NOTHING until the account owner has+ // acknowledged the field list — the backend answers `consent: "unacknowledged"` until then. This+ // flag exists to switch the collector off entirely (tests, air-gapped installs).+ ANALYTICS_ENABLED: z.string().default('true').transform((v) => v !== 'false'),+ // Defaults to BACKEND_WS_URL over https — the ingest endpoint is the same host, and deliberately+ // NOT the adapter socket: analytics must not share a pipe with the E2EE content channel.+ ANALYTICS_BACKEND_URL: z.string().optional(),+ ANALYTICS_FLUSH_INTERVAL_MS: z.string().default('60000').transform(Number),// Set to 'true' to skip auto-installing lifecycle hooks for every supported engine.DISABLE_HOOK_INSTALL: z.string().default('false').transform((v) => v === 'true'),// How often (ms) the reaper checks tmux panes and drops dead sessions.diff --git a/cli/src/engines/types.ts b/cli/src/engines/types.tsindex d64551123..90679d274 100644--- a/cli/src/engines/types.ts+++ b/cli/src/engines/types.ts@@ -1,7 +1,19 @@import type { LiveEvent } from '../lib/normalize.js'import type { RegisteredSession } from '../lib/registry.js'-export type AgentEngine = 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'hermes' | 'commandcode' | 'devin' | 'muse' | 'amp' | 'kilo' | 'grok'+/**+ * Every engine this CLI integrates, as a value.+ *+ * `AgentEngine` alone cannot be iterated, and analytics has to report exactly what it instruments —+ * so the list lives here once and both forms are derived from it. A new engine added to the union+ * without being added here fails to compile.+ */+export const ENGINES = [+ 'claude', 'codex', 'cursor', 'opencode', 'pi', 'hermes',+ 'commandcode', 'devin', 'muse', 'amp', 'kilo', 'grok',+] as const++export type AgentEngine = (typeof ENGINES)[number]export interface EngineNormalizer {ingest(line: string): LiveEvent[]diff --git a/cli/src/lib/analytics/collector.spec.ts b/cli/src/lib/analytics/collector.spec.tsnew file mode 100644index 000000000..5c34dfcb9--- /dev/null+++ b/cli/src/lib/analytics/collector.spec.ts@@ -0,0 +1,281 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { mkdtempSync, rmSync } from 'fs'+import { tmpdir } from 'os'+import { join } from 'path'++const dataDir = mkdtempSync(join(tmpdir(), 'harness-analytics-'))+process.env.ADAPTER_DATA_DIR = dataDir+process.env.ANALYTICS_BACKEND_URL = 'https://backend.test'+process.env.ANALYTICS_ENABLED = 'true'++const { AnalyticsCollector, analyticsBaseUrl, extractEpoch } = await import('./collector.js')+const { disableLocally, enableLocally, renderPreview, UPLOADED_FIELDS } = await import('./command.js')+const { ENGINES } = await import('../../engines/types.js')++const fetchMock = vi.fn()+vi.stubGlobal('fetch', fetchMock)++function respond(body: unknown, status = 200): void {+ fetchMock.mockResolvedValueOnce({ ok: status >= 200 && status < 300, status, json: async () => body })+}++function sent(): Record<string, unknown> {+ const [, init] = fetchMock.mock.calls[fetchMock.mock.calls.length - 1] as [string, { body: string }]+ return JSON.parse(init.body)+}++let clock = Date.parse('2026-08-11T10:00:00Z')++function collector(token: string | null = 'a'.repeat(64)): InstanceType<typeof AnalyticsCollector> {+ const c = new AnalyticsCollector({+ token: () => token,+ enginesPresent: () => ['claude', 'kilo'],+ collectorVersion: '1.2.3',+ now: () => clock,+ })+ c.start()+ return c+}++beforeEach(() => {+ fetchMock.mockReset()+ clock = Date.parse('2026-08-11T10:00:00Z')+ // Consent is persisted on purpose — a restart must not re-upload what the owner turned off — so+ // each test starts from a clean data dir.+ rmSync(join(dataDir, 'analytics'), { recursive: true, force: true })+})++afterEach(() => {+ rmSync(join(dataDir, 'analytics'), { recursive: true, force: true })+})++describe('the funnel hook', () => {+ it('counts a completed turn from the per-session lifecycle events', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ clock += 20 * 60_000+ c.sessionTurnEnded('s1', false)++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()++ const day = (sent().days as { buckets: Record<string, number>[]; machineDay: Record<string, number> }[])[0]+ expect(day.buckets[0].turnsCompleted).toBe(1)+ expect(day.buckets[0].instructions).toBe(1)+ expect(day.machineDay.wallClockActiveMs).toBe(20 * 60_000)+ c.stop()+ })++ it('records an interrupted turn as cancelled, not completed', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'codex', 'agent-1')+ clock += 60_000+ c.sessionTurnEnded('s1', true)++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()++ const day = (sent().days as { buckets: Record<string, number>[] }[])[0]+ expect(day.buckets[0].turnsCancelled).toBe(1)+ expect(day.buckets[0].turnsCompleted).toBe(0)+ c.stop()+ })++ it('closes a leaked turn when the same session starts another one', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ clock += 60_000+ c.sessionTurnStarted('s1', 'claude', 'agent-1') // no turn_ended ever arrived+ clock += 60_000+ c.sessionTurnEnded('s1', false)++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()++ const day = (sent().days as { buckets: Record<string, number>[] }[])[0]+ expect(day.buckets[0].turnsFailed).toBe(1)+ expect(day.buckets[0].turnsCompleted).toBe(1)+ c.stop()+ })++ it('counts one active agent when two sessions belong to it', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)+ c.sessionTurnStarted('s2', 'codex', 'agent-1')+ c.sessionTurnEnded('s2', false)++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()++ const day = (sent().days as { machineDay: { activeAgents: number } }[])[0]+ expect(day.machineDay.activeAgents).toBe(1)+ c.stop()+ })+})++describe('payload', () => {+ it('claims coverage of every engine this CLI integrates', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()++ const body = sent() as { collector: { engineCoverage: string[]; enginesPresent: string[]; version: string } }+ expect(body.collector.engineCoverage).toEqual([...ENGINES])+ expect(body.collector.enginesPresent).toEqual(['claude', 'kilo'])+ expect(body.collector.version).toBe('1.2.3')+ c.stop()+ })++ it('reports mode remote and never puts an agent id on the wire', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'a-very-identifying-agent-name')+ c.sessionTurnEnded('s1', false)++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()++ const raw = JSON.stringify(sent())+ expect(raw).not.toContain('a-very-identifying-agent-name')+ expect(raw).not.toContain('s1')+ const day = (sent().days as { buckets: { mode: string }[] }[])[0]+ expect(day.buckets[0].mode).toBe('remote')+ c.stop()+ })++ it('derives the ingest endpoint from the backend socket host, not the socket itself', () => {+ expect(analyticsBaseUrl()).toBe('https://backend.test')+ })+})++describe('consent', () => {+ it('uploads from the first flush, with no opt-in step', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()++ expect((sent().days as unknown[]).length).toBe(1)+ c.stop()+ })++ it('stops collecting when the owner turns it off', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)++ respond({ data: { consent: 'off', epoch: 0, serverTime: '', accepted: 0, quarantined: 0 } })+ await c.flush()++ c.sessionTurnStarted('s2', 'claude', 'agent-1')+ c.sessionTurnEnded('s2', false)+ fetchMock.mockReset()+ await c.flush()++ expect(fetchMock).not.toHaveBeenCalled()+ c.stop()+ })++ it('obeys `harness analytics off` on this computer whatever the account says', async () => {+ const c = collector()+ disableLocally()++ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)+ await c.flush()+ expect(fetchMock).not.toHaveBeenCalled()++ enableLocally()+ c.sessionTurnStarted('s2', 'claude', 'agent-1')+ c.sessionTurnEnded('s2', false)+ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()+ expect(fetchMock).toHaveBeenCalledTimes(1)+ c.stop()+ })++ it('drops its records when the account history was deleted', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)++ respond({ error: { message: 'Analytics history was reset; current epoch is 9' } }, 409)+ await c.flush()++ fetchMock.mockReset()+ await c.flush()+ expect(fetchMock).not.toHaveBeenCalled()+ c.stop()+ })++ it('keeps the snapshot when the network is down', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)++ fetchMock.mockRejectedValueOnce(new Error('ENOTFOUND'))+ await expect(c.flush()).resolves.toBeUndefined()++ respond({ data: { consent: 'on', epoch: 0, serverTime: '', accepted: 1, quarantined: 0 } })+ await c.flush()+ const day = (sent().days as { buckets: Record<string, number>[] }[])[0]+ expect(day.buckets[0].turnsCompleted).toBe(1)+ c.stop()+ })++ it('does not upload before this computer has joined', async () => {+ const c = collector(null)+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)++ await c.flush()+ expect(fetchMock).not.toHaveBeenCalled()+ c.stop()+ })+})++describe('harness analytics preview', () => {+ it('shows every uploaded field and the never-sent list without contacting the backend', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ clock += 5 * 60_000+ c.sessionTurnEnded('s1', false)+ c.stop() // persists the snapshot the command reads++ const text = renderPreview()++ for (const field of UPLOADED_FIELDS) expect(text).toContain(field)+ expect(text).toContain('what you typed, and what any engine replied')+ expect(text).toContain('uploading')+ expect(text).toContain('2026-08-11')+ expect(fetchMock).not.toHaveBeenCalled()+ })++ it('says so plainly when nothing has been recorded', () => {+ expect(renderPreview()).toContain('Nothing recorded yet')+ })++ it('deletes the local records when switched off', async () => {+ const c = collector()+ c.sessionTurnStarted('s1', 'claude', 'agent-1')+ c.sessionTurnEnded('s1', false)+ c.stop()++ expect(renderPreview()).not.toContain('Nothing recorded yet')+ disableLocally()+ expect(renderPreview()).toContain('Nothing recorded yet')+ enableLocally()+ })+})++describe('extractEpoch', () => {+ it('reads the epoch out of the 409 message', () => {+ expect(extractEpoch('Analytics history was reset; current epoch is 9')).toBe(9)+ expect(extractEpoch('nope')).toBeNull()+ })+})diff --git a/cli/src/lib/analytics/collector.ts b/cli/src/lib/analytics/collector.tsnew file mode 100644index 000000000..7a61ba660--- /dev/null+++ b/cli/src/lib/analytics/collector.ts@@ -0,0 +1,317 @@+/**+ * Harness Analytics collector for the remote CLI.+ *+ * Design: `autonomous-code` docs/design/harness-analytics.md ("Source-specific collectors").+ *+ * This is the collector that matters most: it is the only layer that understands every engine's+ * transcript well enough to count the same concept across all twelve, and it is the only one that+ * can count at all — the relay sees `turn_started` and `turn_ended` as ciphertext+ * (`ENCRYPTED_UP_TYPES` in `src/lib/e2ee/core.ts`), so a byte count there could never distinguish a+ * real instruction from a duplicated control frame.+ *+ * Two behaviours are load-bearing and easy to get wrong:+ *+ * - **Collection starts immediately; uploading waits for acknowledgement.** Aggregates are+ * snapshots, so holding them costs nothing and loses nothing. That is what lets the product be on+ * by default while still being able to say, truthfully, that no byte left this computer before+ * its owner read the field list. The CLI runs headless on servers and under `harness join`, where+ * there is no screen to show a preview on, so the hold is the only honest mechanism available.+ * - **The upload response is the control channel.** A daemon has no other way to learn the owner+ * turned collection off or deleted the history.+ */+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs'+import { dirname, join } from 'path'+import { env } from '../../config/env.js'+import { ENGINES as ALL_ENGINES, type AgentEngine } from '../../engines/types.js'+import { AnalyticsReducer, type ReducerSnapshot } from './reducer.js'+import {+ ANALYTICS_SCHEMA_VERSION,+ MAX_DAYS_PER_REPORT,+ type AnalyticsReportResponse,+ type ConsentState,+ type Engine,+ type Origin,+ type TurnOutcome,+} from './contract.js'++const UPTIME_TICK_MS = 60_000+/** A tick may credit at most this much, so a laptop that slept cannot claim the hours it was shut. */+const UPTIME_MAX_CREDIT_MS = 90_000++interface PersistedState {+ version: 1+ consent: ConsentState+ epoch: number+ reducer: ReducerSnapshot+}++/** Where the daemon keeps its analytics state, beside its other mutable data. */+export function analyticsStateFile(): string {+ return join(env.ADAPTER_DATA_DIR, 'analytics', 'state.json')+}++/** The CLI dials the backend over `wss://`; the ingest endpoint is the same host over `https://`. */+export function analyticsBaseUrl(): string {+ if (env.ANALYTICS_BACKEND_URL) return env.ANALYTICS_BACKEND_URL.replace(/\/$/, '')+ return env.BACKEND_WS_URL.replace(/^ws/, 'http').replace(/\/$/, '')+}++export interface CollectorOptions {+ /** Reads the machine api key. Kept as a callback because the daemon may join after start-up. */+ token: () => string | null+ /**+ * Engines with a registered agent on this computer right now.+ *+ * `engineCoverage` alone cannot answer "is anything being missed": an engine absent from it is+ * either uninstrumented or simply not installed. Only the difference is shown to the user, so the+ * collector has to report what it can actually see.+ */+ enginesPresent: () => AgentEngine[]+ collectorVersion: string+ now?: () => number+}++export class AnalyticsCollector {+ private reducer = new AnalyticsReducer()+ // Collection is ON by default; the backend only ever tells us to stop.+ private consent: ConsentState = 'on'+ private epoch = 0+ private lastTickAt: number+ private uptimeTimer: NodeJS.Timeout | null = null+ private flushTimer: NodeJS.Timeout | null = null+ private started = false+ private flushing = false+ private dirty = false++ /** The CLI instruments every engine it integrates — that is the point of putting it here. */+ private readonly coverage: Engine[] = [...ALL_ENGINES] as Engine[]++ constructor(private readonly opts: CollectorOptions) {+ this.lastTickAt = this.now()+ }++ private now(): number {+ return this.opts.now ? this.opts.now() : Date.now()+ }++ start(): void {+ if (this.started || !env.ANALYTICS_ENABLED) return+ this.started = true+ this.load()+ this.lastTickAt = this.now()++ this.uptimeTimer = setInterval(() => this.tick(), UPTIME_TICK_MS)+ this.uptimeTimer.unref?.()+ this.flushTimer = setInterval(() => { void this.flush() }, env.ANALYTICS_FLUSH_INTERVAL_MS)+ this.flushTimer.unref?.()+ }++ stop(): void {+ this.started = false+ if (this.uptimeTimer) clearInterval(this.uptimeTimer)+ if (this.flushTimer) clearInterval(this.flushTimer)+ this.uptimeTimer = null+ this.flushTimer = null+ this.persist()+ }++ /** Live turn id per session. The normalizers emit per-session lifecycle events, not turn ids. */+ private readonly openTurns = new Map<string, string>()+ private turnSeq = 0++ /**+ * A turn began on a session.+ *+ * Called from the single `emitSessionEvents` funnel, which every engine's normalizer feeds — so one+ * hook covers all twelve, and a thirteenth engine is counted the day it joins that funnel.+ *+ * `agentId` is used ONLY to count distinct active agents for the day and never leaves this+ * computer; the wire payload carries the integer alone.+ */+ sessionTurnStarted(+ sessionId: string,+ engine: AgentEngine,+ agentId: string,+ origin: Origin = 'human',+ at = this.now(),+ ): void {+ if (!this.collecting()) return++ // A previous turn that never terminated would otherwise leak and under-report the day.+ const stale = this.openTurns.get(sessionId)+ if (stale) this.reducer.turnFinished(stale, at, 'failed')++ const turnId = `${sessionId}#${++this.turnSeq}`+ this.openTurns.set(sessionId, turnId)+ this.reducer.turnStarted(turnId, at, engine as Engine, 'remote', origin)+ this.reducer.instruction(at, engine as Engine, 'remote', origin, agentId)+ this.dirty = true+ }++ /** A turn terminated. `aborted` is the normalizers' word for an interrupt. */+ sessionTurnEnded(sessionId: string, aborted: boolean, at = this.now()): void {+ if (!this.collecting()) return+ const turnId = this.openTurns.get(sessionId)+ if (!turnId) return+ this.openTurns.delete(sessionId)+ this.reducer.turnFinished(turnId, at, aborted ? 'cancelled' : 'completed')+ this.dirty = true+ }++ /** A session went away. Its open turn is a failure; dropping it would under-report the day. */+ sessionClosed(sessionId: string, at = this.now()): void {+ const turnId = this.openTurns.get(sessionId)+ if (!turnId) return+ this.openTurns.delete(sessionId)+ if (!this.collecting()) return+ this.reducer.turnFinished(turnId, at, 'failed')+ this.dirty = true+ }++ /** Direct turn control, used by the conformance tests. */+ turnFinished(turnId: string, outcome: TurnOutcome, at = this.now()): void {+ if (!this.collecting()) return+ this.reducer.turnFinished(turnId, at, outcome)+ this.dirty = true+ }++ /**+ * A `harness analytics off` run by the person at this computer wins over anything the account+ * says. It is a marker file rather than a flag in the state JSON because that command is a+ * separate short-lived process and two writers on one snapshot corrupts it.+ */+ private locallyDisabled(): boolean {+ try { return existsSync(join(env.ADAPTER_DATA_DIR, 'analytics', 'disabled')) } catch { return false }+ }++ private collecting(): boolean {+ return this.started && this.consent !== 'off' && !this.locallyDisabled()+ }++ private tick(): void {+ const now = this.now()+ const elapsed = now - this.lastTickAt+ this.lastTickAt = now+ if (!this.collecting()) return+ this.reducer.tickUptime(now, elapsed, UPTIME_MAX_CREDIT_MS)+ this.reducer.closeStaleTurns(now)+ }++ /** The report this computer would send, for `harness analytics preview` — nothing is uploaded. */+ buildReport(now = new Date(this.now())): Record<string, unknown> {+ const days = this.reducer.reportableDays().slice(-MAX_DAYS_PER_REPORT)+ return {+ schemaVersion: ANALYTICS_SCHEMA_VERSION,+ epoch: this.epoch,+ generatedAt: now.toISOString(),+ collector: {+ version: this.opts.collectorVersion,+ engineCoverage: this.coverage,+ enginesPresent: [...new Set(this.opts.enginesPresent())],+ },+ days: days.map((d) => this.reducer.reportFor(d, 'remote')).filter(Boolean),+ }+ }++ consentState(): ConsentState {+ return this.consent+ }++ async flush(now = new Date(this.now())): Promise<void> {+ if (!this.started || this.flushing || this.locallyDisabled()) return+ this.flushing = true+ try {+ if (this.dirty) { this.persist(); this.dirty = false }+ const key = this.opts.token()+ if (!key) return++ const body = this.buildReport(now)+ if ((body.days as unknown[]).length === 0) return++ const res = await fetch(`${analyticsBaseUrl()}/api/analytics/report`, {+ method: 'POST',+ headers: { 'content-type': 'application/json', 'x-api-key': key },+ body: JSON.stringify(body),+ })++ if (res.status === 409) {+ // The owner deleted this account's history. Anything still queued belongs to the old epoch,+ // so it is dropped here rather than uploaded again on the next tick.+ const payload = await res.json().catch(() => null) as { error?: { message?: string } } | null+ this.epoch = extractEpoch(payload?.error?.message) ?? this.epoch + 1+ this.reducer.clear()+ this.persist()+ console.log('[analytics] history was reset centrally; local records dropped')+ return+ }+ if (!res.ok) return // transient: keep the snapshot and retry on the next flush++ const parsed = await res.json().catch(() => null) as { data?: AnalyticsReportResponse } | null+ const result = parsed?.data+ if (!result) return++ this.applyControl(result)+ if (result.accepted > 0) {+ // Keep a two-day tail so a late terminal event can still revise a recently-uploaded day.+ const days = (body.days as { dayUtc: string }[]).map((d) => d.dayUtc)+ this.reducer.forgetBefore(days[Math.max(0, days.length - 2)])+ this.persist()+ }+ } catch {+ // Offline, DNS down, backend restarting. The snapshot survives; the next flush retries.+ } finally {+ this.flushing = false+ }+ }++ private applyControl(result: AnalyticsReportResponse): void {+ const previous = this.consent+ this.consent = result.consent+ this.epoch = result.epoch++ if (result.consent === 'off') {+ this.reducer.clear()+ this.persist()+ if (previous !== 'off') console.log('[analytics] collection turned off by the account owner')+ return+ }+ if (previous !== result.consent) this.persist()+ }++ private load(): void {+ try {+ const parsed = JSON.parse(readFileSync(analyticsStateFile(), 'utf8')) as PersistedState+ if (parsed.version !== 1) return+ this.consent = parsed.consent+ this.epoch = parsed.epoch+ this.reducer = new AnalyticsReducer(parsed.reducer)+ } catch {+ // No state yet, or unreadable. Starting clean loses at most today's counters, which is better+ // than refusing to collect.+ }+ }++ private persist(): void {+ const payload: PersistedState = {+ version: 1,+ consent: this.consent,+ epoch: this.epoch,+ reducer: this.reducer.snapshot(),+ }+ try {+ const target = analyticsStateFile()+ mkdirSync(dirname(target), { recursive: true })+ const tmp = `${target}.tmp`+ writeFileSync(tmp, JSON.stringify(payload), 'utf8')+ renameSync(tmp, target) // atomic: a crash mid-write must not leave a truncated state file+ } catch {+ // A read-only or full disk must not take the daemon down over analytics.+ }+ }+}++/** Pull the current epoch out of the 409 message so the collector resynchronises immediately. */+export function extractEpoch(message: string | undefined): number | null {+ const match = /current epoch is (\d+)/.exec(message ?? '')+ return match ? Number(match[1]) : null+}diff --git a/cli/src/lib/analytics/command.ts b/cli/src/lib/analytics/command.tsnew file mode 100644index 000000000..d68b841ec--- /dev/null+++ b/cli/src/lib/analytics/command.ts@@ -0,0 +1,168 @@+/**+ * `harness analytics` — the local off switch and disclosure.+ *+ * Design: `autonomous-code` docs/design/harness-analytics.md ("Consent and privacy surfaces").+ *+ * Collection is on by default. The web app owns the account-level switch; this command owns what a+ * person sitting at THIS computer can do without a browser: see exactly what is sent, and stop it.+ *+ * `off` writes a marker file rather than editing the daemon's state JSON, because these commands are+ * short-lived processes running alongside a live daemon — two writers on one JSON file is a+ * corrupted snapshot waiting to happen. The daemon polls the marker on its existing tick.+ */+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'+import { dirname, join } from 'path'+import { env } from '../../config/env.js'+import { analyticsBaseUrl, analyticsStateFile } from './collector.js'+import type { DailyReportPayload } from './contract.js'++/** Presence of this file means "this computer does not report", whatever the account says. */+export function analyticsDisabledFile(): string {+ return join(env.ADAPTER_DATA_DIR, 'analytics', 'disabled')+}++export function isLocallyDisabled(): boolean {+ try { return existsSync(analyticsDisabledFile()) } catch { return false }+}++/** Every field that can leave this computer, in the order the collector sends it. */+export const UPLOADED_FIELDS: string[] = [+ 'dayUtc', 'engine', 'mode', 'origin',+ 'instructions', 'turnsStarted', 'turnsCompleted', 'turnsFailed',+ 'turnsCancelled', 'turnsInputNeeded', 'agentRuntimeMs',+ 'wallClockActiveMs', 'activeAgents', 'uptimeMs',+ 'collectorVersion', 'engineCoverage', 'enginesPresent',+]++export const NEVER_SENT: string[] = [+ 'what you typed, and what any engine replied',+ 'file names, paths, code, or repository names',+ 'tool names, tool arguments, or command output',+ 'agent names, session ids, or workspace names',+ 'any per-event timestamp — only daily totals',+]++interface PersistedState {+ version?: number+ consent?: string+ epoch?: number+ reducer?: unknown+}++function readState(): PersistedState | null {+ try { return JSON.parse(readFileSync(analyticsStateFile(), 'utf8')) as PersistedState } catch { return null }+}++/**+ * Render the local report.+ *+ * Deliberately reads the daemon's persisted snapshot rather than asking the backend: the whole point+ * is to show what WOULD be sent, from a computer that may never have uploaded anything.+ */+export function localReport(): { days: DailyReportPayload[]; consent: string; epoch: number } {+ const state = readState()+ const reducer = state?.reducer as { days?: Record<string, unknown> } | undefined+ const dayKeys = Object.keys(reducer?.days ?? {}).sort()+ const days: DailyReportPayload[] = []++ for (const key of dayKeys) {+ const day = (reducer?.days as Record<string, {+ buckets?: Record<string, Record<string, number>>+ intervals?: [number, number][]+ agents?: string[]+ uptimeMs?: number+ }>)[key]+ const buckets = Object.entries(day.buckets ?? {}).map(([bucketKey, counters]) => {+ const [engine, mode, origin] = bucketKey.split('|')+ return { engine, mode, origin, ...counters } as unknown as DailyReportPayload['buckets'][number]+ })+ days.push({+ dayUtc: key,+ machineDay: {+ wallClockActiveMs: (day.intervals ?? []).reduce((acc, [s, e]) => acc + (e - s), 0),+ activeAgents: (day.agents ?? []).length,+ uptimeMs: day.uptimeMs ?? 0,+ reported: true,+ },+ buckets,+ })+ }++ return { days, consent: state?.consent ?? 'on', epoch: state?.epoch ?? 0 }+}++function duration(ms: number): string {+ const minutes = Math.round(ms / 60000)+ const hours = Math.floor(minutes / 60)+ return hours === 0 ? `${minutes}m` : `${hours}h ${String(minutes % 60).padStart(2, '0')}m`+}++export function renderPreview(): string {+ const { days, consent, epoch } = localReport()+ const out: string[] = []++ out.push('Harness Analytics — what this computer would send')+ out.push('')+ out.push(` upload state ${isLocallyDisabled() ? 'off on this computer' : describeConsent(consent)}`)+ out.push(` endpoint ${analyticsBaseUrl()}/api/analytics/report`)+ out.push(` epoch ${epoch}`)+ out.push('')+ out.push('FIELDS — one row per engine, per day')+ out.push('')+ for (const field of UPLOADED_FIELDS) out.push(` ${field}`)+ out.push('')+ out.push('NEVER SENT')+ out.push('')+ for (const item of NEVER_SENT) out.push(` × ${item}`)+ out.push('')++ if (days.length === 0) {+ out.push('Nothing recorded yet. Figures appear after your next agent turn.')+ return out.join('\n')+ }++ out.push(`RECORDED LOCALLY — ${days.length} day${days.length === 1 ? '' : 's'}`)+ out.push('')+ for (const day of days.slice(-14)) {+ const instructions = day.buckets.reduce((a, b) => a + b.instructions, 0)+ const completed = day.buckets.reduce((a, b) => a + b.turnsCompleted, 0)+ const failed = day.buckets.reduce((a, b) => a + b.turnsFailed + b.turnsCancelled, 0)+ out.push(+ ` ${day.dayUtc} ${String(instructions).padStart(4)} instructions` ++ ` ${String(completed).padStart(4)} completed` ++ ` ${String(failed).padStart(3)} failed/cancelled` ++ ` ${duration(day.machineDay.wallClockActiveMs).padStart(8)} active`,+ )+ }+ out.push('')+ out.push('No prompt content is included, here or in what is uploaded.')+ return out.join('\n')+}++function describeConsent(consent: string): string {+ if (consent === 'off') return 'off (the account owner turned it off)'+ // Collection is on by default; anything that is not an explicit off is uploading.+ return 'uploading'+}++export function disableLocally(): string {+ const target = analyticsDisabledFile()+ mkdirSync(dirname(target), { recursive: true })+ writeFileSync(target, `${new Date().toISOString()}\n`, 'utf8')+ // Drop what was already collected: leaving it would upload the moment someone re-enabled.+ try { rmSync(analyticsStateFile(), { force: true }) } catch { /* nothing to drop */ }+ return 'Analytics is off on this computer. Local records were deleted.\nTurn it back on with: harness analytics on'+}++export function enableLocally(): string {+ try { rmSync(analyticsDisabledFile(), { force: true }) } catch { /* already on */ }+ return 'Analytics is on for this computer.'+}++/** Dispatch for `harness analytics [preview|on|off]`. */+export function runAnalyticsCommand(sub: string | undefined): string {+ if (sub === 'off') return disableLocally()+ if (sub === 'on') return enableLocally()+ if (!sub || sub === 'preview' || sub === 'status' || sub === 'report') return renderPreview()+ return `Unknown subcommand "${sub}".\nUsage: harness analytics [preview|on|off]`+}diff --git a/cli/src/lib/analytics/contract.spec.ts b/cli/src/lib/analytics/contract.spec.tsnew file mode 100644index 000000000..8e11cd987--- /dev/null+++ b/cli/src/lib/analytics/contract.spec.ts@@ -0,0 +1,42 @@+import { describe, expect, it } from 'vitest'+import { ENGINES as CONTRACT_ENGINES, MODES, ORIGINS, TURN_OUTCOMES, utcDayKey } from './contract.js'+import { ENGINES } from '../../engines/types.js'+import { ENCRYPTED_UP_TYPES } from '../e2ee/core.js'++/**+ * Drift guards.+ *+ * `contract.ts` is a hand-kept mirror of `autonomous-code`'s copy — the two repositories share no+ * package — so nothing but a test stops the copies from diverging. A thirteenth engine that reaches+ * the CLI without reaching the analytics contract would silently report nothing, which the design+ * names as the most damaging failure this product can have.+ */+describe('engine parity', () => {+ it('counts exactly the engines this CLI integrates', () => {+ expect([...CONTRACT_ENGINES].sort()).toEqual([...ENGINES].sort())+ })+})++describe('lifecycle classification', () => {+ it('still counts at the layer that can see plaintext', () => {+ // If these frames stopped being encrypted the collector could in principle move; while they ARE+ // encrypted, the relay cannot count them and this collector is the only layer that can.+ expect(ENCRYPTED_UP_TYPES.has('turn_started')).toBe(true)+ expect(ENCRYPTED_UP_TYPES.has('turn_ended')).toBe(true)+ })+})++describe('vocabulary', () => {+ it('pins the dimensions the backend indexes on', () => {+ expect([...MODES]).toEqual(['self', 'managed', 'remote', 'provider'])+ expect([...ORIGINS]).toEqual(['human', 'scheduled', 'system', 'api'])+ expect([...TURN_OUTCOMES]).toEqual(['completed', 'failed', 'cancelled', 'input_required'])+ })++ it('agrees with the backend on what a day is', () => {+ // Both sides key records by UTC midnight; a local-time day would move a machine's records the+ // moment it travelled.+ expect(utcDayKey('2026-08-11T23:59:59Z')).toBe('2026-08-11')+ expect(utcDayKey('2026-08-12T00:00:00Z')).toBe('2026-08-12')+ })+})diff --git a/cli/src/lib/analytics/contract.ts b/cli/src/lib/analytics/contract.tsnew file mode 100644index 000000000..db314e6b2--- /dev/null+++ b/cli/src/lib/analytics/contract.ts@@ -0,0 +1,163 @@+/**+ * Harness Analytics — the canonical, versioned contract.+ *+ * MIRROR of `autonomous-code`: apps/backend/src/types/analytics.ts. The two repositories share no+ * package, so the copies are kept in sync by the conformance tests rather than by the module+ * system. Edit the backend copy first, then mirror it here.+ *+ *+ * Design: docs/design/harness-analytics.md+ *+ * The one rule that shapes everything here: ADDITIVE counters and NON-ADDITIVE metrics travel in+ * different shapes. `DailyBucket` may be split by engine/mode/origin and re-summed; `MachineDay`+ * may not, so it exists once per (machine, day) and is computed locally where every interval is+ * visible.+ */++export const ANALYTICS_SCHEMA_VERSION = 1++export const ENGINES = [+ 'claude', 'codex', 'cursor', 'opencode', 'pi', 'hermes',+ 'commandcode', 'devin', 'muse', 'amp', 'kilo', 'grok',+] as const+export type Engine = (typeof ENGINES)[number]++export const MODES = ['self', 'managed', 'remote', 'provider'] as const+export type Mode = (typeof MODES)[number]++export const ORIGINS = ['human', 'scheduled', 'system', 'api'] as const+export type Origin = (typeof ORIGINS)[number]++export const TURN_OUTCOMES = ['completed', 'failed', 'cancelled', 'input_required'] as const+export type TurnOutcome = (typeof TURN_OUTCOMES)[number]++/**+ * Collection is ON by default and can be turned off; there is no pending state.+ *+ * An earlier design held every upload until the account owner had acknowledged a field list. That+ * gate was removed deliberately: it put a full-page interstitial in front of the dashboard, and the+ * disclosure now lives as a non-blocking panel instead.+ */+export const CONSENT_STATES = ['on', 'off'] as const+export type ConsentState = (typeof CONSENT_STATES)[number]++/**+ * Canonical activity events, emitted at the normalization boundary — before E2EE sealing on the+ * remote CLI, because the relay cannot tell a real instruction from a duplicated control frame.+ *+ * `agentId` NEVER leaves the machine. It is present so the local reducer can compute a distinct+ * active-agent count; only the resulting integer is uploaded.+ */+export type AnalyticsEventV1 =+ | { type: 'instruction'; eventId: string; at: string; engine: Engine; origin: Origin }+ | { type: 'turn_started'; turnId: string; at: string; engine: Engine; origin: Origin; agentId: string }+ | { type: 'turn_finished'; turnId: string; at: string; outcome: TurnOutcome }++/** ADDITIVE counters for one (day, engine, mode, origin). Safe to sum along any dimension. */+export interface DailyBucketPayload {+ engine: Engine+ mode: Mode+ origin: Origin+ instructions: number+ turnsStarted: number+ turnsCompleted: number+ turnsFailed: number+ turnsCancelled: number+ turnsInputNeeded: number+ /** Sum of terminal turn durations. Concurrent agents overlap here by design. */+ agentRuntimeMs: number+}++/**+ * NON-ADDITIVE metrics for one (machine, day), plus the reporting heartbeat.+ *+ * Emitted for EVERY day the collector was alive, including an all-zero day: that is what lets the+ * dashboard tell "up and idle" from "no data". A missing day is missing information, never zero.+ */+export interface MachineDayPayload {+ /** Union of turn intervals — computed here, where the whole set is visible, and never split. */+ wallClockActiveMs: number+ /** Distinct agents with at least one accepted human instruction. */+ activeAgents: number+ /** Denominator for utilization. 0 when not meaningful (provider mode has no container). */+ uptimeMs: number+ reported: boolean+}++export interface DailyReportPayload {+ /** Midnight UTC of the day, ISO-8601 (`2026-08-11` or a full timestamp). */+ dayUtc: string+ machineDay: MachineDayPayload+ buckets: DailyBucketPayload[]+}++export interface CollectorInfo {+ version: string+ /** Engines this collector actually instruments. */+ engineCoverage: Engine[]+ /**+ * Engines the collector can SEE on this machine (registered agents, discovered binaries).+ *+ * Coverage alone cannot answer "is anything being missed": an engine absent from `engineCoverage`+ * is either uninstrumented or simply not installed, and reporting every engine the product knows+ * about as "not instrumented" would be noise on every machine. The difference+ * `enginesPresent - engineCoverage` is the honest set, and it is the only one the UI shows.+ */+ enginesPresent: Engine[]+}++/** Request body of `POST /api/analytics/report`. */+export interface AnalyticsReportRequest {+ schemaVersion: number+ /** Account deletion epoch the collector last saw. An older epoch is refused. */+ epoch: number+ /** Client monotonic stamp; the server clamps it against its own clock. */+ generatedAt: string+ collector: CollectorInfo+ days: DailyReportPayload[]+}++/**+ * Response of `POST /api/analytics/report`. This doubles as the control channel: it is the only way+ * a headless collector learns that the owner turned collection off or deleted the history.+ */+export interface AnalyticsReportResponse {+ consent: ConsentState+ epoch: number+ serverTime: string+ accepted: number+ quarantined: number+}++/**+ * How far a client stamp may sit from the server clock before its records are quarantined rather+ * than stored. A machine whose clock is years off would otherwise write into a bucket far outside+ * the range and take over every chart.+ */+export const CLOCK_SKEW_TOLERANCE_MS = 48 * 60 * 60 * 1000++/** Days accepted in one report. A backlog flush after a long offline period needs several. */+export const MAX_DAYS_PER_REPORT = 120++/** Central retention for daily records: 13 months, so year-over-year views have a comparison. */+export const RETENTION_DAYS = 396++/** Buckets accepted for one day: 12 engines x 4 modes x 4 origins, with headroom. */+export const MAX_BUCKETS_PER_DAY = 240++/** Below this many terminal turns, a completion rate is suppressed instead of shown. */+export const MIN_SAMPLE_FOR_RATE = 30++/** Days of history required before an anomaly baseline is meaningful. */+export const MIN_DAYS_FOR_BASELINE = 14++/** Midnight UTC of the day containing `at`. The single definition of a day, used on both sides. */+export function utcDayStart(at: Date | string): Date {+ const d = typeof at === 'string' ? new Date(at) : at+ return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()))+}++/** `2026-08-11` — the wire form of a day key. */+export function utcDayKey(at: Date | string): string {+ return utcDayStart(at).toISOString().slice(0, 10)+}diff --git a/cli/src/lib/analytics/reducer.spec.ts b/cli/src/lib/analytics/reducer.spec.tsnew file mode 100644index 000000000..4a198fda5--- /dev/null+++ b/cli/src/lib/analytics/reducer.spec.ts@@ -0,0 +1,198 @@+import { describe, expect, it } from 'vitest'+import { AnalyticsReducer, mergeInterval, splitAcrossDays, unionMs } from './reducer.js'++const MIN = 60_000+const HOUR = 60 * MIN+const DAY = 24 * HOUR++const at = (iso: string): number => Date.parse(iso)++function reducer(): AnalyticsReducer {+ return new AnalyticsReducer()+}++describe('interval union', () => {+ it('merges overlapping intervals instead of adding them', () => {+ let merged: [number, number][] = []+ merged = mergeInterval(merged, 0, 25 * MIN)+ merged = mergeInterval(merged, 5 * MIN, 30 * MIN)++ expect(merged).toEqual([[0, 30 * MIN]])+ expect(unionMs(merged)).toBe(30 * MIN)+ })++ it('keeps disjoint intervals apart', () => {+ let merged: [number, number][] = []+ merged = mergeInterval(merged, 0, 10 * MIN)+ merged = mergeInterval(merged, 40 * MIN, 50 * MIN)++ expect(unionMs(merged)).toBe(20 * MIN)+ })++ it('closes a gap when a later interval bridges two existing ones', () => {+ let merged: [number, number][] = []+ merged = mergeInterval(merged, 0, 10 * MIN)+ merged = mergeInterval(merged, 40 * MIN, 50 * MIN)+ merged = mergeInterval(merged, 5 * MIN, 45 * MIN)++ expect(merged).toEqual([[0, 50 * MIN]])+ })+})++/**+ * The first of the two additivity fixtures the design requires as permanent regressions.+ */+describe('overlapping turns on different engines', () => {+ it('sums runtime but unions wall-clock time', () => {+ const r = reducer()+ r.turnStarted('a', at('2026-08-11T10:00:00Z'), 'claude', 'managed', 'human')+ r.turnStarted('b', at('2026-08-11T10:05:00Z'), 'codex', 'managed', 'human')+ r.turnFinished('a', at('2026-08-11T10:25:00Z'), 'completed')+ r.turnFinished('b', at('2026-08-11T10:30:00Z'), 'completed')++ const day = r.reportFor('2026-08-11', 'managed')!+ const runtime = day.buckets.reduce((acc, b) => acc + b.agentRuntimeMs, 0)++ expect(runtime).toBe(50 * MIN)+ expect(day.machineDay.wallClockActiveMs).toBe(30 * MIN)+ })+})++/**+ * The second fixture: one agent, two origins, must still be one active agent.+ */+describe('one agent across two origins', () => {+ it('counts the agent once while splitting its counters by origin', () => {+ const r = reducer()+ r.instruction(at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'human', 'agent-1')+ r.instruction(at('2026-08-11T11:00:00Z'), 'claude', 'managed', 'human', 'agent-1')+ r.turnStarted('s', at('2026-08-11T12:00:00Z'), 'claude', 'managed', 'scheduled')+ r.turnFinished('s', at('2026-08-11T12:10:00Z'), 'completed')++ const day = r.reportFor('2026-08-11', 'managed')!++ expect(day.machineDay.activeAgents).toBe(1)+ expect(day.buckets).toHaveLength(2)+ expect(day.buckets.find((b) => b.origin === 'human')!.instructions).toBe(2)+ expect(day.buckets.find((b) => b.origin === 'scheduled')!.turnsCompleted).toBe(1)+ })++ it('does not count a scheduled turn towards active agents', () => {+ const r = reducer()+ r.instruction(at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'scheduled', 'agent-1')++ expect(r.reportFor('2026-08-11', 'managed')!.machineDay.activeAgents).toBe(0)+ })+})++describe('midnight', () => {+ it('splits a turn across the UTC day boundary', () => {+ expect(splitAcrossDays(at('2026-08-11T23:30:00Z'), at('2026-08-12T00:30:00Z'))).toEqual([+ { start: at('2026-08-11T23:30:00Z'), end: at('2026-08-12T00:00:00Z') },+ { start: at('2026-08-12T00:00:00Z'), end: at('2026-08-12T00:30:00Z') },+ ])+ })++ it('attributes runtime to both days and the outcome to the day it ended', () => {+ const r = reducer()+ r.turnStarted('t', at('2026-08-11T23:30:00Z'), 'claude', 'managed', 'human')+ r.turnFinished('t', at('2026-08-12T00:30:00Z'), 'completed')++ const first = r.reportFor('2026-08-11', 'managed')!+ const second = r.reportFor('2026-08-12', 'managed')!++ expect(first.machineDay.wallClockActiveMs).toBe(30 * MIN)+ expect(second.machineDay.wallClockActiveMs).toBe(30 * MIN)+ expect(first.buckets.reduce((a, b) => a + b.turnsCompleted, 0)).toBe(0)+ expect(second.buckets.reduce((a, b) => a + b.turnsCompleted, 0)).toBe(1)+ })+})++describe('stale turns', () => {+ it('closes a turn the machine never finished, instead of losing the day', () => {+ const r = reducer()+ r.turnStarted('t', at('2026-08-11T10:00:00Z'), 'claude', 'managed', 'human')++ expect(r.closeStaleTurns(at('2026-08-11T12:00:00Z'))).toBe(0)+ expect(r.closeStaleTurns(at('2026-08-13T10:00:00Z'))).toBe(1)++ const day = r.reportFor('2026-08-12', 'managed')!+ expect(day.buckets.reduce((a, b) => a + b.turnsFailed, 0)).toBe(1)+ })++ it('ignores a turn_finished for an id it never saw start', () => {+ const r = reducer()+ r.turnFinished('ghost', at('2026-08-11T10:00:00Z'), 'completed')++ expect(r.reportFor('2026-08-11', 'managed')).toBeNull()+ })+})++describe('heartbeat and uptime', () => {+ it('emits reported:true on a day with no activity at all', () => {+ const r = reducer()+ r.tickUptime(at('2026-08-11T10:00:00Z'), 60_000, 90_000)++ const day = r.reportFor('2026-08-11', 'managed')!+ expect(day.machineDay.reported).toBe(true)+ expect(day.machineDay.wallClockActiveMs).toBe(0)+ expect(day.buckets).toHaveLength(0)+ })++ it('caps a single uptime credit so a suspended container cannot claim the gap', () => {+ const r = reducer()+ r.tickUptime(at('2026-08-11T10:00:00Z'), 6 * HOUR, 90_000)++ expect(r.reportFor('2026-08-11', 'managed')!.machineDay.uptimeMs).toBe(90_000)+ })++ it('splits an uptime credit that spans midnight', () => {+ const r = reducer()+ r.tickUptime(at('2026-08-12T00:00:30Z'), 60_000, 90_000)++ expect(r.reportFor('2026-08-11', 'managed')!.machineDay.uptimeMs).toBe(30_000)+ expect(r.reportFor('2026-08-12', 'managed')!.machineDay.uptimeMs).toBe(30_000)+ })+})++describe('persistence', () => {+ it('survives a restart with its open turns intact', () => {+ const first = reducer()+ first.turnStarted('t', at('2026-08-11T10:00:00Z'), 'claude', 'managed', 'human')++ const revived = new AnalyticsReducer(JSON.parse(JSON.stringify(first.snapshot())))+ revived.turnFinished('t', at('2026-08-11T10:20:00Z'), 'completed')++ expect(revived.reportFor('2026-08-11', 'managed')!.machineDay.wallClockActiveMs).toBe(20 * MIN)+ })++ it('forgets days already stored centrally', () => {+ const r = reducer()+ r.tickUptime(at('2026-08-09T10:00:00Z'), 60_000, 90_000)+ r.tickUptime(at('2026-08-11T10:00:00Z'), 60_000, 90_000)+ r.forgetBefore('2026-08-11')++ expect(r.reportableDays()).toEqual(['2026-08-11'])+ })++ it('keeps the local store bounded', () => {+ const r = reducer()+ const base = at('2020-01-01T00:00:00Z')+ for (let i = 0; i < 130; i++) r.tickUptime(base + i * DAY, 1000, 90_000)++ expect(r.reportableDays().length).toBeLessThanOrEqual(120)+ })+})++describe('privacy', () => {+ it('never puts an agent id on the wire', () => {+ const r = reducer()+ r.instruction(at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'human', 'secret-agent-name')+ r.turnStarted('t', at('2026-08-11T09:00:00Z'), 'claude', 'managed', 'human')+ r.turnFinished('t', at('2026-08-11T09:10:00Z'), 'completed')++ const wire = JSON.stringify(r.reportFor('2026-08-11', 'managed'))+ expect(wire).not.toContain('secret-agent-name')+ expect(JSON.parse(wire).machineDay.activeAgents).toBe(1)+ })+})diff --git a/cli/src/lib/analytics/reducer.ts b/cli/src/lib/analytics/reducer.tsnew file mode 100644index 000000000..fd003a7ae--- /dev/null+++ b/cli/src/lib/analytics/reducer.ts@@ -0,0 +1,305 @@+/**+ * Harness Analytics — the local reducer.+ *+ * Design: docs/design/harness-analytics.md ("Local reducer and daily aggregates").+ *+ * This is where the additive/non-additive split is actually produced. Counters are accumulated per+ * (day, engine, mode, origin); the union of turn intervals and the distinct agent count are computed+ * HERE, per (machine, day), because this is the only place the whole set of intervals is visible.+ * Splitting either of them by engine and re-summing later is the bug this shape exists to prevent.+ *+ * Nothing in this file keeps prompt text, tool data, file names, or timestamps beyond the day+ * totals. `agentId` is held only long enough to count distinct agents and is never emitted.+ */+import {+ utcDayKey,+ type DailyBucketPayload,+ type DailyReportPayload,+ type Engine,+ type Mode,+ type Origin,+ type TurnOutcome,+} from './contract.js'++const DAY_MS = 24 * 60 * 60 * 1000++/** A turn still open after this long is closed as failed — the machine was almost certainly killed. */+export const STALE_TURN_MS = 24 * 60 * 60 * 1000++/** Days retained locally. Aggregates are tiny, but the queue must still be bounded. */+export const MAX_LOCAL_DAYS = 120++type BucketKey = string // `${engine}|${mode}|${origin}`++interface Counters {+ instructions: number+ turnsStarted: number+ turnsCompleted: number+ turnsFailed: number+ turnsCancelled: number+ turnsInputNeeded: number+ agentRuntimeMs: number+}++interface DayState {+ buckets: Record<BucketKey, Counters>+ /** Merged, disjoint, sorted [startMs, endMs) offsets within the day. */+ intervals: [number, number][]+ /** Agent ids with at least one accepted human instruction. Never leaves this process. */+ agents: string[]+ uptimeMs: number+}++interface OpenTurn {+ turnId: string+ startedAt: number+ engine: Engine+ mode: Mode+ origin: Origin+}++export interface ReducerSnapshot {+ version: 1+ days: Record<string, DayState>+ openTurns: Record<string, OpenTurn>+}++function emptyCounters(): Counters {+ return {+ instructions: 0,+ turnsStarted: 0,+ turnsCompleted: 0,+ turnsFailed: 0,+ turnsCancelled: 0,+ turnsInputNeeded: 0,+ agentRuntimeMs: 0,+ }+}++function emptyDay(): DayState {+ return { buckets: {}, intervals: [], agents: [], uptimeMs: 0 }+}++function dayStartMs(at: number): number {+ const d = new Date(at)+ return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate())+}++/**+ * Merge `[start, end)` into a disjoint sorted interval set.+ *+ * This is the union that makes wall-clock time honest: two agents working 10:00-10:25 and+ * 10:05-10:30 contribute 30 minutes here, while their runtimes contribute 50 minutes to the+ * additive counter. Both numbers are correct and they answer different questions.+ */+export function mergeInterval(+ intervals: [number, number][],+ start: number,+ end: number,+): [number, number][] {+ if (end <= start) return intervals+ const out: [number, number][] = []+ let lo = start+ let hi = end+ let inserted = false+ for (const [s, e] of intervals) {+ if (e < lo) {+ out.push([s, e])+ } else if (s > hi) {+ if (!inserted) { out.push([lo, hi]); inserted = true }+ out.push([s, e])+ } else {+ lo = Math.min(lo, s)+ hi = Math.max(hi, e)+ }+ }+ if (!inserted) out.push([lo, hi])+ return out.sort((a, b) => a[0] - b[0])+}++export function unionMs(intervals: [number, number][]): number {+ return intervals.reduce((acc, [s, e]) => acc + (e - s), 0)+}++/**+ * The reducer.+ *+ * Deliberately pure with respect to time: every entry point takes an explicit timestamp, so the+ * midnight-split, stale-turn, and uptime behaviours are testable without waiting for a clock.+ */+export class AnalyticsReducer {+ private days = new Map<string, DayState>()+ private open = new Map<string, OpenTurn>()++ constructor(snapshot?: ReducerSnapshot) {+ if (snapshot?.version === 1) {+ for (const [day, state] of Object.entries(snapshot.days)) this.days.set(day, state)+ for (const [id, turn] of Object.entries(snapshot.openTurns)) this.open.set(id, turn)+ }+ }++ snapshot(): ReducerSnapshot {+ return {+ version: 1,+ days: Object.fromEntries(this.days),+ openTurns: Object.fromEntries(this.open),+ }+ }++ private day(key: string): DayState {+ let state = this.days.get(key)+ if (!state) {+ state = emptyDay()+ this.days.set(key, state)+ this.prune()+ }+ return state+ }++ private counters(dayKey: string, engine: Engine, mode: Mode, origin: Origin): Counters {+ const state = this.day(dayKey)+ const key: BucketKey = `${engine}|${mode}|${origin}`+ state.buckets[key] = state.buckets[key] ?? emptyCounters()+ return state.buckets[key]+ }++ private prune(): void {+ if (this.days.size <= MAX_LOCAL_DAYS) return+ const sorted = [...this.days.keys()].sort()+ for (const key of sorted.slice(0, this.days.size - MAX_LOCAL_DAYS)) this.days.delete(key)+ }++ /**+ * A human instruction was accepted. Called only for turns the normalizer classified as real user+ * input — system prompts, tool results, replay, and compaction never reach here.+ */+ instruction(at: number, engine: Engine, mode: Mode, origin: Origin, agentId?: string): void {+ const key = utcDayKey(new Date(at))+ this.counters(key, engine, mode, origin).instructions+++ if (origin === 'human' && agentId) {+ const state = this.day(key)+ if (!state.agents.includes(agentId)) state.agents.push(agentId)+ }+ }++ turnStarted(turnId: string, at: number, engine: Engine, mode: Mode, origin: Origin): void {+ this.counters(utcDayKey(new Date(at)), engine, mode, origin).turnsStarted+++ this.open.set(turnId, { turnId, startedAt: at, engine, mode, origin })+ }++ /**+ * Close a turn.+ *+ * The outcome counts on the day the turn ENDED, which is one arbitrary choice made consistently+ * and stated in the metric tooltip. Runtime and the wall-clock union are split at the UTC day+ * boundary, so a turn running across midnight contributes to both days truthfully.+ */+ turnFinished(turnId: string, at: number, outcome: TurnOutcome): void {+ const turn = this.open.get(turnId)+ if (!turn) return+ this.open.delete(turnId)+ const end = Math.max(at, turn.startedAt)++ const counters = this.counters(utcDayKey(new Date(end)), turn.engine, turn.mode, turn.origin)+ if (outcome === 'completed') counters.turnsCompleted+++ else if (outcome === 'failed') counters.turnsFailed+++ else if (outcome === 'cancelled') counters.turnsCancelled+++ else counters.turnsInputNeeded++++ for (const slice of splitAcrossDays(turn.startedAt, end)) {+ const key = utcDayKey(new Date(slice.start))+ const base = dayStartMs(slice.start)+ this.counters(key, turn.engine, turn.mode, turn.origin).agentRuntimeMs += slice.end - slice.start+ const state = this.day(key)+ state.intervals = mergeInterval(state.intervals, slice.start - base, slice.end - base)+ }+ }++ /**+ * Close turns that outlived any plausible run.+ *+ * Without this a machine killed mid-turn would leave the turn open forever: its runtime would+ * never land anywhere and the day would silently under-report. Truncating at the last observed+ * event and calling it `failed` is the honest reading of "we stopped hearing about it".+ */+ closeStaleTurns(now: number): number {+ let closed = 0+ for (const [id, turn] of [...this.open]) {+ if (now - turn.startedAt < STALE_TURN_MS) continue+ this.turnFinished(id, turn.startedAt + STALE_TURN_MS, 'failed')+ closed+++ }+ return closed+ }++ /**+ * Credit time the collector was alive, for the utilization denominator.+ *+ * Bounded per call so a suspended container that wakes up hours later does not credit the gap: we+ * only know the process was running when it was actually ticking.+ */+ tickUptime(now: number, elapsedMs: number, maxCreditMs: number): void {+ const credit = Math.max(0, Math.min(elapsedMs, maxCreditMs))+ if (credit === 0) return+ for (const slice of splitAcrossDays(now - credit, now)) {+ this.day(utcDayKey(new Date(slice.start))).uptimeMs += slice.end - slice.start+ }+ }++ /** Days that have any activity or any credited uptime — i.e. days this collector was alive. */+ reportableDays(): string[] {+ return [...this.days.keys()].sort()+ }++ /**+ * Build the wire payload for a day.+ *+ * `reported: true` on an all-zero day is the heartbeat: it is what lets the dashboard say "up and+ * idle" instead of leaving a gap that looks identical to a machine that was switched off.+ */+ reportFor(dayKey: string, mode: Mode): DailyReportPayload | null {+ const state = this.days.get(dayKey)+ if (!state) return null+ const buckets: DailyBucketPayload[] = Object.entries(state.buckets).map(([key, counters]) => {+ const [engine, bucketMode, origin] = key.split('|') as [Engine, Mode, Origin]+ return { engine, mode: bucketMode, origin, ...counters }+ })+ void mode+ return {+ dayUtc: dayKey,+ machineDay: {+ wallClockActiveMs: unionMs(state.intervals),+ activeAgents: state.agents.length,+ uptimeMs: state.uptimeMs,+ reported: true,+ },+ buckets,+ }+ }++ /** Drop everything. Used when the account turns collection off or deletes its history. */+ clear(): void {+ this.days.clear()+ this.open.clear()+ }++ /** Forget days already stored centrally, keeping a small tail in case a later revision arrives. */+ forgetBefore(dayKey: string): void {+ for (const key of [...this.days.keys()]) {+ if (key < dayKey) this.days.delete(key)+ }+ }+}++/** Split `[start, end)` at UTC midnights, so no interval is ever attributed to the wrong day. */+export function splitAcrossDays(start: number, end: number): { start: number; end: number }[] {+ const out: { start: number; end: number }[] = []+ let cursor = start+ while (cursor < end) {+ const boundary = dayStartMs(cursor) + DAY_MS+ const stop = Math.min(end, boundary)+ out.push({ start: cursor, end: stop })+ cursor = stop+ }+ return out+}