Skip to content

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.

feat(product): measure what the dial is used for, and keep it when the laptop is shut

0xdiego25d94ef7975443
diff --git a/cli/src/cable/cableHost.ts b/cli/src/cable/cableHost.ts
index 63b9a6684..ba384491f 100644
--- a/cli/src/cable/cableHost.ts
+++ b/cli/src/cable/cableHost.ts
@@ -18,6 +18,7 @@ import { routeVoiceTask, type RouterAgent, type RouterContinuity } from '../lib/
import { env } from '../config/env.js'
import type { CableAgent, CableHost, CableMachine, CableMachineSource, RouteDecision } from './cableSession.js'
+import type { ProductEvent } from '../lib/product/events.js'
import type { WindowRoute } from './windowRoute.js'
import { FleetError, type FleetMachine, type MachineFleet } from './machineFleet.js'
@@ -32,6 +33,11 @@ export interface RecentTurn {
export interface CableHostWiring {
/** The person's own last questions to a LOCAL agent, newest first. */
recentAsks: (agentId: string) => string[]
+ /**
+ * Report what somebody did on the dial. Optional — a host wired without it
+ * behaves identically, which is what every test in this package relies on.
+ */
+ trackDial?: (event: ProductEvent) => void
machineName: () => string
/** This computer's machineId, or '' when the daemon has never resolved one (signed out). */
machineId: () => string
@@ -630,6 +636,10 @@ export class DaemonCableHost implements CableHost {
* a turn ended without one. Folding them together is what left the newest question — the one that
* says where the next one belongs — off the end.
*/
+ trackDial(event: ProductEvent): void {
+ this.wiring.trackDial?.(event)
+ }
+
async recentAsks(agentId: string): Promise<string[]> {
const raw = this.isLocalAgent(agentId)
? this.wiring.recentAsks(agentId)
diff --git a/cli/src/cable/cableSession.ts b/cli/src/cable/cableSession.ts
index db2dbeb40..10077afb7 100644
--- a/cli/src/cable/cableSession.ts
+++ b/cli/src/cable/cableSession.ts
@@ -34,6 +34,18 @@ const PING_EVERY_MS = 5_000
/** No bytes of any kind for this long → the handle is dead. Longer than the dial's own 15 s window, so a
* single late message cannot trip both sides at once and have each conclude the other left. */
const SILENCE_MS = 20_000
+
+/** How often an attached dial reports that it is still there, and how busy. */
+const HEARTBEAT_EVERY_MS = 5 * 60_000
+
+/**
+ * Corrupt frames in one beat that make a wire worth reporting.
+ *
+ * Not one: a single bad checkcode is the normal cost of a cable being moved, and
+ * an event for each would drown the stream. Ten in five minutes is a link that
+ * is not working.
+ */
+const CORRUPT_FRAMES_FAULT = 10
const REOPEN_EVERY_MS = 2_000
// How long one attempt at opening the port may take before it is abandoned.
//
@@ -173,6 +185,7 @@ export type CableMachineSource = 'backend' | 'local' | 'signed-out'
export type { WindowRoute } from './windowRoute.js'
import type { WindowRoute } from './windowRoute.js'
+import { dialEvents, type ProductEvent } from '../lib/product/events.js'
export interface RouteDecision {
agentId: string
@@ -244,6 +257,14 @@ export interface CableHost {
* Optional: a host with no window to ask simply omits it, and voice behaves exactly as it always has.
*/
routeInWindow?(text: string, cmd?: string): Promise<WindowRoute>
+ /**
+ * Report what somebody did on the dial.
+ *
+ * Optional, and never awaited: the session must behave identically with no
+ * collector wired, which is what every test here relies on and what keeps an
+ * analytics fault from ever reaching the path that carries a person's words.
+ */
+ trackDial?(event: ProductEvent): void
/** The runtime model/effort catalog for one agent, as opaque profile ids the dial groups and shows. */
listModels(agentId: string): Promise<string[]>
/** One agent's last turn summaries, newest first — what a reattached dial needs to redraw its tiles. */
@@ -300,11 +321,36 @@ export class CableSession {
private timer: NodeJS.Timeout | null = null
private greetedMac: string | null = null
private greetedFw: string | null = null
+ /** What an in-flight OTA is moving between, for `dial_fw_update`. */
+ private offeringFrom = ''
+ private offeringTo = ''
+
+ /** Frames since the dial greeted — see the note in onMessage. */
+ private dialFrames = 0
+ /** When the current dial attached, for `dial_detached` and the heartbeat. */
+ private dialSince = 0
+ /** Frames already reported, so a heartbeat counts the interval and not the run. */
+ private dialFramesReported = 0
+
private lastRx = 0
private stopped = false
/** What the dial was last told the agent list is. Empty = it has been told nothing. */
private lastAgentsKey = ''
+
+ /**
+ * Which engine each agent runs, for the events below.
+ *
+ * Filled from the list the dial is sent, which is the only place the whole set
+ * passes through this class. A lookup rather than an RPC: reporting an event
+ * must never be a round trip on the path that carries a person's turn.
+ */
+ private engineById = new Map<string, string>()
+
+ /** The engine, or '' when this session has not been told about that agent. */
+ private engineOf(agentId: string): string {
+ return this.engineById.get(agentId) ?? ''
+ }
/** Bytes and frames seen since this port opened — the evidence for the foreign-dial verdict. */
private bytesSinceOpen = 0
private framesSinceOpen = 0
@@ -427,6 +473,16 @@ export class CableSession {
}
// Rule 2. The read never fails on a dead handle, so silence is the only symptom there is.
if (Date.now() - this.lastRx > SILENCE_MS) {
+ // A DIAL THAT STOPPED ANSWERING while it was still plugged in. This is the
+ // one shape of the freeze bug this side can see without guessing: the
+ // firmware greets every 15s, so twenty seconds of nothing from an attached
+ // dial is the device having stopped, not a person having walked away.
+ //
+ // Deliberately NOT the detector this was first designed with — "frames
+ // arriving but no interaction for N minutes". People do not touch a dial
+ // continuously, so that would have reported a fault every lunch break and
+ // buried the real ones.
+ if (this.dialSince > 0) this.host.trackDial?.(dialEvents.fault('silence'))
this.host.log('cable: silent, reopening the port')
// close() runs onClosed, which is where onDialGone fires — one path for "the dial is not there",
// whether the cable was pulled or the far end simply stopped answering.
@@ -436,6 +492,33 @@ export class CableSession {
}
// The cadence is the contract: the dial reads a gap as absence, and the tick that watches for that
// gap runs far more often than the ping that prevents it.
+ // One heartbeat every five minutes while a dial is attached.
+ //
+ // Not per gesture and not per frame: the question is "how long is this thing
+ // used for", and the answer is an interval count. `frames` is reported as the
+ // DIFFERENCE since the last beat, so each event describes its own five
+ // minutes rather than the whole session — which is what makes them summable.
+ if (this.dialSince > 0 && Date.now() - this.lastHeartbeat >= HEARTBEAT_EVERY_MS) {
+ this.lastHeartbeat = Date.now()
+ // A WIRE THAT IS MANGLING FRAMES, reported at most once per beat.
+ //
+ // The decoder counts these already and nothing has ever read the counter.
+ // A handful over a session is a cable being jostled; a rate that climbs is
+ // a fault, and it is invisible from the dial's side because the frames it
+ // sends look fine leaving.
+ const corrupt = this.decoder.corruptFrames - this.corruptReported
+ if (corrupt >= CORRUPT_FRAMES_FAULT) {
+ this.corruptReported = this.decoder.corruptFrames
+ this.host.trackDial?.(dialEvents.fault('corrupt_frames'))
+ }
+ this.host.trackDial?.(
+ dialEvents.heartbeat(
+ HEARTBEAT_EVERY_MS / 60_000,
+ this.dialFrames - this.dialFramesReported,
+ ),
+ )
+ this.dialFramesReported = this.dialFrames
+ }
if (Date.now() - this.lastPing >= PING_EVERY_MS) {
this.lastPing = Date.now()
await this.send({ t: 'ping' })
@@ -459,6 +542,8 @@ export class CableSession {
private openAt = 0
private opening = false
private lastPing = 0
+ private lastHeartbeat = 0
+ private corruptReported = 0
/**
* Open the dial's port, at most ONE attempt at a time.
@@ -606,6 +691,12 @@ export class CableSession {
const str = (key: string): string | undefined =>
typeof msg[key] === 'string' ? (msg[key] as string) : undefined
+ // EVERY DIAL FRAME PASSES HERE, which is why the counting is done in one
+ // place rather than sprinkled through the cases below. `frames` is what
+ // separates a dial being driven from one powered on at the back of a desk;
+ // the two are identical in attach/detach alone.
+ this.dialFrames++
+
switch (msg.t) {
case 'hello': {
// ⚠️ A POSITIVE MATCH, AND ABSENCE MEANS NO. The framing magic already stops the sibling product's
@@ -628,6 +719,15 @@ export class CableSession {
return
}
const mac = str('mac') ?? ''
+ // ATTACHED, once per dial rather than once per greeting — hello arrives
+ // every 15s, and a stream with four events a minute per device saying
+ // "still plugged in" is a stream nobody can afford to keep.
+ if (this.dialSince === 0) {
+ this.dialSince = Date.now()
+ this.dialFrames = 0
+ this.dialFramesReported = 0
+ this.host.trackDial?.(dialEvents.attached(str('fw') ?? '?', CABLE_PROTO_VERSION))
+ }
// Rule 1: every greeting is answered, but only an unfamiliar dial gets the full state.
await this.send({
t: 'welcome',
@@ -675,6 +775,9 @@ export class CableSession {
await this.syncMachines(true)
return
case 'machine.select':
+ // No machine id in the event: WHICH machine is a name, and this stream
+ // carries counts. Whether the wheel is used at all is the question.
+ this.host.trackDial?.(dialEvents.machineSelected())
await this.selectMachine(str('machineId') ?? '')
return
case 'models.list': {
@@ -735,6 +838,10 @@ export class CableSession {
}
return
case 'agent.open':
+ // `dial` because this arrived FROM the device. The app-led case reports
+ // itself in followApp — which of the two screens leads is the question
+ // the pair answers, and it needs both halves to mean anything.
+ this.host.trackDial?.(dialEvents.agentOpened('dial'))
if (str('agentId')) this.host.openAgent(str('agentId')!)
return
case 'scroll': {
@@ -745,10 +852,20 @@ export class CableSession {
if (phase !== 'down' && phase !== 'move' && phase !== 'up') return
const dy = typeof msg.dy === 'number' ? msg.dy : 0
const v = typeof msg.v === 'number' ? msg.v : 0
+ // ONE EVENT PER STROKE, not per frame. A `move` arrives every few
+ // milliseconds while a finger is down; counting those would drown every
+ // other event in this stream several times over and say nothing that
+ // the completed gesture does not.
+ if (phase === 'up') this.host.trackDial?.(dialEvents.navigated('scroll', 0))
this.host.scrolled(phase, dy, v)
return
}
case 'turn.send':
+ // The ENGINE and nothing else. Not the text, not its length — a length
+ // is a fingerprint of what somebody wrote.
+ if (str('agentId')) {
+ this.host.trackDial?.(dialEvents.turnSent(this.engineOf(str('agentId')!), 'type'))
+ }
if (str('agentId') && str('text')) this.host.sendTurn(str('agentId')!, str('text')!)
return
case 'turn.stop':
@@ -766,11 +883,18 @@ export class CableSession {
for (const [k, v] of Object.entries(answers as Record<string, unknown>)) {
if (typeof v === 'string') flat[k] = v
}
+ // The outcome, never the answer: an option's key is the wording of
+ // a question this daemon has no business carrying.
+ this.host.trackDial?.(dialEvents.answer('answered'))
this.host.answer(agentId, requestId, flat)
}
return
}
case 'agent.update':
+ // WHICH setting, not what it was set to: a model name is a choice worth
+ // counting, and it is already counted on the app's side.
+ if (str('model')) this.host.trackDial?.(dialEvents.settingChanged('model'))
+ if (str('effort')) this.host.trackDial?.(dialEvents.settingChanged('effort'))
if (str('agentId')) this.host.updateAgent(str('agentId')!, str('model'), str('effort'))
return
case 'voice.begin':
@@ -862,6 +986,8 @@ export class CableSession {
this.offered.add(offerKey)
this.host.log(`cable: offering firmware ${candidate.version} (${candidate.image.length} B)`)
+ this.offeringFrom = this.greetedFw ?? '?'
+ this.offeringTo = candidate.version
this.transfer = new FirmwareTransfer(
candidate.image,
candidate.version,
@@ -919,9 +1045,24 @@ export class CableSession {
//
// The window DELIVERS what it picks, so there is nothing left to send here: a `sent` outcome is
// already on its way to an agent, and calling sendTurn on it would deliver the sentence twice.
+ // ONE EVENT PER CAPTURE, wherever it ends up, reported from here because
+ // this is the only place that sees both the outcome and which router
+ // produced it. `routed` is the measurement the window-route change was
+ // made without: whether the palette actually takes these, or whether the
+ // fallback is doing the work.
const inWindow = this.host.routeInWindow
? await this.host.routeInWindow(transcript, turn.cmd)
: ({ t: 'unavailable' } as const)
+ // `seconds` is the AUDIO's length, computed above — the length of what was
+ // said rather than how long the round trip took, which is the honest
+ // reading and does not move with the network.
+ this.host.trackDial?.(
+ dialEvents.voice(
+ inWindow.t === 'sent' ? 'sent' : inWindow.t,
+ seconds,
+ inWindow.t === 'unavailable' ? 'host' : 'window',
+ ),
+ )
if (inWindow.t === 'sent') {
this.host.log(`cable: the window routed the spoken task → ${inWindow.agentId.slice(0, 8)}`)
await this.send({
@@ -1014,6 +1155,7 @@ export class CableSession {
const key = CableSession.agentsKey(agents)
if (!force && key === this.lastAgentsKey) return
this.lastAgentsKey = key
+ this.engineById = new Map(agents.map((a) => [a.id, a.engine ?? '']))
// Every push, and only pushes. The dial showing a different number from the daemon is a question this
// line answers in one look: either the daemon never said it, or it said it and the dial disagreed.
this.host.log(`cable: agents → ${agents.length}${force ? ' (attach)' : ''}`)
@@ -1227,6 +1369,12 @@ export class CableSession {
if (!this.link?.isOpen || this.greetedMac === null) return
if (!agentId) return
+ // The OTHER half of `dial_agent_opened`. On its own, "the dial opened an
+ // agent" cannot tell a person driving the device from a device trailing the
+ // window — and which of the two screens leads is the whole question about
+ // what the dial is for.
+ this.host.trackDial?.(dialEvents.agentOpened('app_follow'))
+
const generation = ++this.appFocusGeneration
const task = this.appFocusTail.then(async () => {
// A newer desktop selection made this queued one obsolete before it started.
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 58762727e..430004ad8 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -101,6 +101,7 @@ import { createWindowRouter } from './cable/windowRoute.js'
import { RemoteRelayPool } from './lib/remoteRelay.js'
import { TERMINAL_BINARY_VERSION } from './lib/terminalBinary.js'
import { foldTranscript, lastTurnTextFromRawLines, lineToEvents, newTurnState, type LiveEvent, type TurnState } from './lib/normalize.js'
+import { ProductCollector } from './lib/product/collector.js'
import { AnalyticsCollector } from './lib/analytics/collector.js'
import { runAnalyticsCommand } from './lib/analytics/command.js'
import { AskQuestionController, pollsQuestions, QuestionWatcher } from './lib/askQuestion.js'
@@ -1378,6 +1379,15 @@ async function runForeground(session: AuthSession): Promise<void> {
* That hold is what lets the CLI be on by default while running headless, where there is no screen
* to show a preview on.
*/
+ // The DIAL's behaviour stream — a different thing from the AnalyticsCollector
+ // below, which counts agent work. See lib/product/events.ts for why the two
+ // live apart.
+ const product = new ProductCollector({
+ computerId: () => computerId(),
+ log: (line) => console.log(line),
+ })
+ product.start()
+
const analytics = new AnalyticsCollector({
token: () => readAuthSession()?.accessToken ?? null,
enginesPresent: () => [...new Set(registry.list().map((entry) => entry.engine))],
@@ -4029,6 +4039,10 @@ async function runForeground(session: AuthSession): Promise<void> {
answer: (agentId, requestId, answers) => backend.onQuestionAnswer?.({ agentId, requestId, answers }),
recent: (id, n) => mirror.recent(registry.resolve(id)?.sessionId || id, n),
recentAsks: (id) => mirror.recentAsks(registry.resolve(id)?.sessionId || id),
+ // Never awaited, and the collector itself never throws: an analytics detail
+ // sits directly under the path that carries a person's words and must not be
+ // able to cost them a turn.
+ trackDial: (event) => product.track(event),
runtimeProfile: (session) => runtimeProfiles.selectedModel(session),
updateAgent: (agentId, model, effort) => {
const s = registry.resolve(agentId)
diff --git a/cli/src/config/env.ts b/cli/src/config/env.ts
index bab9cec15..c16f0918e 100644
--- a/cli/src/config/env.ts
+++ b/cli/src/config/env.ts
@@ -230,6 +230,10 @@ const envSchema = z.object({
.default(join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'devin', 'config.json')),
// Where the tmux-session registry and daemon-local state are persisted.
ADAPTER_DATA_DIR: z.string().default(adapterDataDir),
+ // Turns the DIAL's behaviour stream off from this side. The user's own switch
+ // is the desktop app's analytics.json (see lib/product/collector.ts); this is
+ // for a machine that never runs the app, and for tests.
+ PRODUCT_ANALYTICS_DISABLED: z.coerce.boolean().default(false),
// This computer's stable id, minted once and never regenerated (see computerIdFile above). Pin it
// explicitly on a box with no durable home — a container or CI job that gets a fresh ~/.harness on
// every boot would otherwise look like a NEW computer each time and collect a machine per start.
diff --git a/cli/src/lib/product/collector.spec.ts b/cli/src/lib/product/collector.spec.ts
new file mode 100644
index 000000000..f0c55cda0
--- /dev/null
+++ b/cli/src/lib/product/collector.spec.ts
@@ -0,0 +1,227 @@
+// The dial's behaviour collector.
+//
+// Two properties carry this file. First, that it NEVER costs a turn: no throw
+// reaches a caller, from a bad event, a dead network or an unwritable disk —
+// this sits directly under the path carrying a person's words. Second, that a
+// session with no network is not a session that was lost, because a dial driven
+// on a shut laptop is the most interesting way the thing gets used.
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, dirname } from 'node:path'
+
+const dataDir = mkdtempSync(join(tmpdir(), 'product-'))
+
+vi.mock('../../config/env.js', () => ({
+ env: { ADAPTER_DATA_DIR: join(dataDir, 'cli', 'data'), PRODUCT_ANALYTICS_DISABLED: false },
+}))
+
+const { ProductCollector, productSpoolFile, trackingDisabled } = await import('./collector.js')
+const { dialEvents, isValidProductEvent } = await import('./events.js')
+
+function make(send: (body: unknown) => Promise<boolean>) {
+ return new ProductCollector({ computerId: () => 'computer-1', send })
+}
+
+beforeEach(() => {
+ try {
+ rmSync(productSpoolFile(), { force: true })
+ } catch { /* nothing spooled yet */ }
+ try {
+ rmSync(join(dataDir, 'cli', 'desktop-app'), { recursive: true, force: true })
+ } catch { /* no switch written */ }
+})
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('ProductCollector', () => {
+ it('sends what it is given, with the computer id and the category', async () => {
+ const sent: Array<Record<string, unknown>> = []
+ const c = make(async (body) => { sent.push(body as Record<string, unknown>); return true })
+ c.start()
+ c.track(dialEvents.attached('0.0.49', 3))
+ await c.flush()
+ expect(sent).toHaveLength(1)
+ expect(sent[0]).toMatchObject({
+ event_name: 'dial_attached',
+ user_pseudo_id: 'computer-1',
+ category: 'harness-dial',
+ })
+ })
+
+ it('keeps events across a restart when the network is down', async () => {
+ // The case the desktop app's in-memory queue gives up on, and the reason
+ // this one writes to disk: a laptop shut, moved, and opened somewhere else.
+ const offline = make(async () => false)
+ offline.start()
+ offline.track(dialEvents.turnSent('claude', 'voice'))
+ offline.track(dialEvents.navigated('scroll', 3))
+ await offline.flush()
+ expect(offline.pending()).toBe(2)
+
+ const sent: unknown[] = []
+ const later = make(async (body) => { sent.push(body); return true })
+ later.start()
+ expect(later.pending()).toBe(2)
+ await later.flush()
+ expect(sent).toHaveLength(2)
+ expect(later.pending()).toBe(0)
+ })
+
+ it('drains oldest first and stops at the first refusal', async () => {
+ // These are one person's session in order. Skipping past a failure would
+ // leave the stream out of sequence for as long as the failure lasts.
+ const seen: string[] = []
+ let allow = 1
+ const c = make(async (body) => {
+ const name = (body as { event_name: string }).event_name
+ if (seen.length >= allow) return false
+ seen.push(name)
+ return true
+ })
+ c.start()
+ c.track(dialEvents.attached('1', 3))
+ c.track(dialEvents.turnSent('claude', 'type'))
+ c.track(dialEvents.detached('unplugged', 5))
+ await c.flush()
+ expect(seen).toEqual(['dial_attached'])
+ expect(c.pending()).toBe(2)
+
+ allow = 3
+ await c.flush()
+ expect(seen).toEqual(['dial_attached', 'dial_turn_sent', 'dial_detached'])
+ })
+
+ it('never throws when the transport does', async () => {
+ const c = make(async () => { throw new Error('socket died') })
+ c.start()
+ c.track(dialEvents.fault('frozen'))
+ await expect(c.flush()).resolves.toBeUndefined()
+ expect(c.pending()).toBe(1)
+ })
+
+ it('refuses a malformed event rather than putting it in a shared stream', () => {
+ const c = make(async () => true)
+ c.start()
+ c.track({ name: 'Dial Attached', params: {}, at: Date.now() })
+ c.track({ name: 'ok_name', params: { bad: { nested: 1 } as never }, at: Date.now() })
+ expect(c.pending()).toBe(0)
+ })
+
+ it('queues nothing before start', () => {
+ const c = make(async () => true)
+ c.track(dialEvents.attached('1', 3))
+ expect(c.pending()).toBe(0)
+ })
+
+ it('drops a 4xx rather than blocking everything behind it', async () => {
+ // Retrying an event the service has refused would wedge the queue for good.
+ let calls = 0
+ const c = new ProductCollector({
+ computerId: () => 'c',
+ send: undefined,
+ })
+ vi.stubGlobal('fetch', async () => { calls++; return new Response('no', { status: 422 }) })
+ c.start()
+ c.track(dialEvents.answer('answered'))
+ await c.flush()
+ expect(calls).toBe(1)
+ expect(c.pending()).toBe(0)
+ })
+
+ it('caps the spool and keeps the NEWEST', async () => {
+ const c = make(async () => false)
+ c.start()
+ for (let i = 0; i < 520; i++) c.track(dialEvents.navigated('scroll', i))
+ expect(c.pending()).toBe(500)
+ const spooled = JSON.parse(readFileSync(productSpoolFile(), 'utf8')) as Array<{ params: { ring_depth: number } }>
+ expect(spooled[spooled.length - 1].params.ring_depth).toBe(519)
+ })
+
+ it('survives a corrupt spool instead of refusing to start', () => {
+ mkdirSync(dirname(productSpoolFile()), { recursive: true })
+ writeFileSync(productSpoolFile(), '{ not json')
+ const c = make(async () => true)
+ c.start()
+ expect(c.pending()).toBe(0)
+ })
+})
+
+describe('the user switch', () => {
+ const switchFile = () => join(dataDir, 'cli', 'desktop-app', 'analytics.json')
+
+ it('is off when the desktop app says tracking is off', () => {
+ // ONE switch for one person. Honouring it in the window and not in the
+ // daemon would make the setting a lie.
+ mkdirSync(dirname(switchFile()), { recursive: true })
+ writeFileSync(switchFile(), JSON.stringify({ enabled: false }))
+ expect(trackingDisabled()).toBe(true)
+ })
+
+ it('is on when the file says so, and when there is no file at all', () => {
+ mkdirSync(dirname(switchFile()), { recursive: true })
+ writeFileSync(switchFile(), JSON.stringify({ enabled: true }))
+ expect(trackingDisabled()).toBe(false)
+ rmSync(switchFile())
+ // A computer that has never run the desktop app is not one that opted out.
+ expect(trackingDisabled()).toBe(false)
+ })
+
+ it('queues nothing while it is off', () => {
+ mkdirSync(dirname(switchFile()), { recursive: true })
+ writeFileSync(switchFile(), JSON.stringify({ enabled: false }))
+ const c = make(async () => true)
+ c.start()
+ c.track(dialEvents.turnSent('claude', 'voice'))
+ expect(c.pending()).toBe(0)
+ rmSync(switchFile())
+ })
+
+ it('throws away what was already spooled when it is turned off', async () => {
+ const c = make(async () => false)
+ c.start()
+ c.track(dialEvents.turnSent('claude', 'voice'))
+ expect(c.pending()).toBe(1)
+ mkdirSync(dirname(switchFile()), { recursive: true })
+ writeFileSync(switchFile(), JSON.stringify({ enabled: false }))
+ await c.flush()
+ // Turning it off has to reach the backlog too, or the next time the network
+ // comes back it sends everything the person just said no to.
+ expect(c.pending()).toBe(0)
+ rmSync(switchFile())
+ })
+})
+
+describe('the events themselves', () => {
+ it('carry no names, no text and no paths', () => {
+ // The rule this stream is held to, checked on the shapes rather than trusted
+ // to review: counts, durations, short codes and ids.
+ const all = [
+ dialEvents.attached('0.0.49', 3),
+ dialEvents.detached('unplugged', 12),
+ dialEvents.heartbeat(5, 210),
+ dialEvents.turnSent('claude', 'voice'),
+ dialEvents.voice('sent', 4, 'window'),
+ dialEvents.navigated('swipe', 2),
+ dialEvents.machineSelected(),
+ dialEvents.agentOpened('dial'),
+ dialEvents.answer('answered'),
+ dialEvents.settingChanged('brightness'),
+ dialEvents.firmwareUpdate('0.0.48', '0.0.49', 'installed'),
+ dialEvents.fault('frozen'),
+ ]
+ for (const event of all) {
+ expect(isValidProductEvent(event), event.name).toBe(true)
+ for (const value of Object.values(event.params)) {
+ if (typeof value !== 'string') continue
+ expect(value).not.toMatch(/[/\\]/)
+ expect(value.length).toBeLessThan(40)
+ }
+ }
+ })
+
+ it('rounds durations, so a timing is never a fingerprint', () => {
+ expect(dialEvents.heartbeat(5.7, 3).params.minutes).toBe(6)
+ expect(dialEvents.voice('sent', 4.49, 'window').params.seconds).toBe(4)
+ })
+})
diff --git a/cli/src/lib/product/collector.ts b/cli/src/lib/product/collector.ts
new file mode 100644
index 000000000..3a8f36fa7
--- /dev/null
+++ b/cli/src/lib/product/collector.ts
@@ -0,0 +1,226 @@
+/**
+ * Sends the dial's behaviour events, and does not lose them when the machine is
+ * offline.
+ *
+ * SPOOLED TO DISK, unlike the desktop app's queue — which says of itself: "Not
+ * persisted across launches: a machine quit while offline loses what was
+ * queued." That is a reasonable trade for a window somebody is sitting in front
+ * of, and the wrong one here. A dial is driven on a laptop that is shut, moved,
+ * and opened somewhere else; the sessions that happen with no network are not an
+ * edge case, they are the ones worth measuring.
+ *
+ * FAILS QUIET, ALWAYS. Nothing here throws into a caller and nothing is awaited
+ * by the cable session. An analytics detail must never be able to cost somebody
+ * a turn, and this code sits directly under the path that carries their words.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { env } from '../../config/env.js'
+import {
+ PRODUCT_CATEGORY,
+ isValidProductEvent,
+ type ProductEvent,
+} from './events.js'
+
+/** Autonomous Analytics. One event per request — the service has no batch route. */
+const ENDPOINT = 'https://autonomous-analytics-qffztaoryq-uc.a.run.app/api/v1/event_tracking'
+
+/**
+ * The same write key the desktop app ships.
+ *
+ * Which is the same one GRID ships, and that is a known, deliberate state rather
+ * than an oversight: both desktop apps append into one analytics project and are
+ * separable only by `category`. It is recorded in the app's AnalyticsConfig with
+ * the reasoning and a TODO; this file inherits both.
+ */
+const WRITE_KEY = 'tBCs0oLwgFgf1borYn54cjHz4fvWahyV'
+
+/** How long one send may take. A wedged host must not hold a spool flush open. */
+const SEND_TIMEOUT_MS = 8_000
+
+/** Events kept on disk. Past this the oldest go — a backlog nobody will read. */
+const MAX_SPOOLED = 500
+
+/** How often the queue drains, when there is anything in it. */
+const FLUSH_INTERVAL_MS = 30_000
+
+export function productSpoolFile(): string {
+ return join(env.ADAPTER_DATA_DIR, 'product', 'dial-events.json')
+}
+
+/**
+ * The user's own switch, read from the DESKTOP APP's file.
+ *
+ * One switch for one person, not two. Somebody who turned tracking off in the
+ * window has said what they want; asking them again in a CLI flag — or worse,
+ * honouring it in one place and not the other — would make the setting a lie.
+ */
+export function trackingDisabled(): boolean {
+ if (env.PRODUCT_ANALYTICS_DISABLED) return true
+ try {
+ const path = join(dirname(env.ADAPTER_DATA_DIR), 'desktop-app', 'analytics.json')
+ const parsed = JSON.parse(readFileSync(path, 'utf8')) as { enabled?: unknown }
+ return parsed.enabled === false
+ } catch {
+ // Absent or unreadable is the normal state on a computer that has never run
+ // the desktop app, and it means "not turned off" — not "refuse to send".
+ return false
+ }
+}
+
+export interface CollectorOptions {
+ /**
+ * The durable id for this computer — `~/.harness/computer-id`.
+ *
+ * Passed in rather than read here, and a callback rather than a value: the
+ * daemon resolves it once and may do so after this is constructed. It is the
+ * SAME file the desktop app uses for its `user_pseudo_id`, which is what makes
+ * the dial's events and the window's events join without anything being
+ * agreed between them.
+ */
+ computerId: () => string
+ log?: (line: string) => void
+ /** Test seam. Defaults to the real endpoint. */
+ send?: (body: unknown) => Promise<boolean>
+ now?: () => number
+}
+
+export class ProductCollector {
+ private queue: ProductEvent[] = []
+ private timer: NodeJS.Timeout | null = null
+ private flushing = false
+ private started = false
+
+ constructor(private readonly opts: CollectorOptions) {}
+
+ start(): void {
+ if (this.started) return
+ this.started = true
+ this.queue = this.readSpool()
+ this.timer = setInterval(() => void this.flush(), FLUSH_INTERVAL_MS)
+ // Never the reason a daemon stays alive at shutdown.
+ this.timer.unref?.()
+ }
+
+ async stop(): Promise<void> {
+ if (this.timer) clearInterval(this.timer)
+ this.timer = null
+ this.started = false
+ await this.flush()
+ this.writeSpool()
+ }
+
+ /**
+ * Queue one event. Never throws, never awaits.
+ *
+ * Dropped rather than corrected when malformed: an event with a bad name or a
+ * non-scalar param is this daemon's own instrumentation being wrong, and
+ * sending it would put a row nobody can query into a stream shared with two
+ * other products.
+ */
+ track(event: ProductEvent): void {
+ if (!this.started || trackingDisabled()) return
+ if (!isValidProductEvent(event)) {
+ this.opts.log?.(`[product] refusing a malformed event: ${event.name}`)
+ return
+ }
+ this.queue.push(event)
+ if (this.queue.length > MAX_SPOOLED) {
+ // The OLDEST go. A backlog this deep means weeks offline, and the recent
+ // events are the ones anybody will act on.
+ this.queue.splice(0, this.queue.length - MAX_SPOOLED)
+ }
+ this.writeSpool()
+ }
+
+ /** For tests and for `stop`. */
+ pending(): number {
+ return this.queue.length
+ }
+
+ /**
+ * Drain what is queued, oldest first, and stop at the first refusal.
+ *
+ * ORDER MATTERS AND SO DOES STOPPING. These are a person's session in
+ * sequence; sending the newest because the oldest failed would leave the
+ * stream out of order for as long as the failure lasts. One failure means the
+ * network or the service, so the rest would fail too.
+ */
+ async flush(): Promise<void> {
+ if (this.flushing || this.queue.length === 0) return
+ if (trackingDisabled()) {
+ this.queue = []
+ this.writeSpool()
+ return
+ }
+ this.flushing = true
+ try {
+ while (this.queue.length > 0) {
+ const event = this.queue[0]
+ const ok = await this.post(event)
+ if (!ok) break
+ this.queue.shift()
+ }
+ this.writeSpool()
+ } finally {
+ this.flushing = false
+ }
+ }
+
+ private async post(event: ProductEvent): Promise<boolean> {
+ const body = {
+ event_name: event.name,
+ event_timestamp: event.at,
+ user_pseudo_id: this.opts.computerId(),
+ category: PRODUCT_CATEGORY,
+ params: event.params,
+ }
+ if (this.opts.send) {
+ try {
+ return await this.opts.send(body)
+ } catch {
+ return false
+ }
+ }
+ try {
+ const res = await fetch(ENDPOINT, {
+ method: 'POST',
+ // Verbatim, with no `Bearer` prefix — what the service reads and what
+ // every other client sends.
+ headers: { 'content-type': 'application/json', authorization: WRITE_KEY },
+ body: JSON.stringify(body),
+ signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+ })
+ // A 4xx that is not 408/429 means THIS event is wrong, and retrying it
+ // forever would block every event behind it. Dropped and counted as sent.
+ if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
+ this.opts.log?.(`[product] ${event.name} refused (${res.status}) — dropping it`)
+ return true
+ }
+ return res.ok
+ } catch {
+ return false
+ }
+ }
+
+ private readSpool(): ProductEvent[] {
+ try {
+ const raw = JSON.parse(readFileSync(productSpoolFile(), 'utf8')) as unknown
+ if (!Array.isArray(raw)) return []
+ return raw.filter((e): e is ProductEvent => isValidProductEvent(e as ProductEvent))
+ } catch {
+ return []
+ }
+ }
+
+ private writeSpool(): void {
+ try {
+ const path = productSpoolFile()
+ mkdirSync(dirname(path), { recursive: true })
+ writeFileSync(path, JSON.stringify(this.queue))
+ } catch {
+ // A disk that will not take it is not worth a line every thirty seconds.
+ }
+ }
+}
diff --git a/cli/src/lib/product/events.ts b/cli/src/lib/product/events.ts
new file mode 100644
index 000000000..cd6a1ce0e
--- /dev/null
+++ b/cli/src/lib/product/events.ts
@@ -0,0 +1,187 @@
+/**
+ * What the dial is used for — behaviour, not agent work.
+ *
+ * TWO ANALYTICS SYSTEMS LIVE IN THIS CLI AND THEY MEASURE DIFFERENT THINGS. The
+ * one in `lib/analytics/` counts agent WORK: turns, runtimes, active agents,
+ * aggregated per day and uploaded to this product's own backend. This one counts
+ * what a PERSON did with the hardware, as individual events, and sends them to
+ * Autonomous Analytics — the same stream the desktop app and the website report
+ * into.
+ *
+ * They are separate directories on purpose. Six months from now the difference
+ * between them is not going to be obvious from a function name, and the cost of
+ * getting it wrong is a metric that silently means something else.
+ *
+ * COLLECTED HERE, NOT IN THE APP. `harness start` runs this daemon on its own and
+ * the dial keeps working with the window closed — which is the most interesting
+ * way the thing gets used, since a dial you can drive without opening an app is
+ * most of its reason to exist. Relaying through the app would lose exactly that.
+ *
+ * THE IDENTITY JOINS FOR FREE. The id below is read from `~/.harness/computer-id`,
+ * which is the same file the desktop app uses for its own `user_pseudo_id`. The
+ * dial's events and the window's events land in one stream already keyed the
+ * same way; nothing had to be agreed between them.
+ *
+ * WHAT NEVER LEAVES THIS PROCESS: a transcript, a recap, an agent's name, a
+ * machine's name, the text of a card. Counts, durations, short codes and ids.
+ * The rule is the desktop app's, written down once there and honoured here.
+ */
+
+/** Tells this stream apart from the app's (`harness-desktop`) and Grid's. */
+export const PRODUCT_CATEGORY = 'harness-dial'
+
+/** `snake_case`, 3–64 chars — the desktop app's rule, so one stream reads one way. */
+export const PRODUCT_EVENT_NAME = /^[a-z][a-z0-9_]{2,63}$/
+
+export interface ProductEvent {
+ name: string
+ params: Record<string, string | number | boolean>
+ /** Client stamp, ms. The server clamps it; a spooled event keeps its own. */
+ at: number
+}
+
+/**
+ * The events this daemon sends, one function each.
+ *
+ * A closed list rather than free-form `track()` calls at the sites, for the
+ * reason the app's `AnalyticsEvents` extension exists: two call sites that name
+ * the same action differently is a stream nobody can query, and the only place
+ * that can prevent it is the one place the names are written down.
+ */
+export const dialEvents = {
+ /** A dial came up on the cable. */
+ attached: (fw: string, proto: number): ProductEvent => ({
+ name: 'dial_attached',
+ params: { fw, proto },
+ at: Date.now(),
+ }),
+
+ /**
+ * It went away, and how long it had been there.
+ *
+ * `reason` is a short code — `unplugged`, `rebooting`, `error`, `shutdown` —
+ * never a message, which can carry a device path.
+ */
+ detached: (reason: string, minutesAttached: number): ProductEvent => ({
+ name: 'dial_detached',
+ params: { reason, minutes_attached: Math.round(minutesAttached) },
+ at: Date.now(),
+ }),
+
+ /**
+ * Still here, and this much happened.
+ *
+ * The only way to answer "how long is it used for" without a timer per
+ * gesture. `frames` separates a dial being driven from one sitting powered on
+ * at the back of the desk — the two look identical in attach/detach alone.
+ */
+ heartbeat: (minutes: number, frames: number): ProductEvent => ({
+ name: 'dial_heartbeat',
+ params: { minutes: Math.round(minutes), frames },
+ at: Date.now(),
+ }),
+
+ /** A turn sent from the dial. `via` is `voice` or `type`. */
+ turnSent: (engine: string, via: string): ProductEvent => ({
+ name: 'dial_turn_sent',
+ params: { engine, via },
+ at: Date.now(),
+ }),
+
+ /**
+ * One voice capture, end to end.
+ *
+ * `routed` is `window` when the desktop palette decided and `host` when this
+ * daemon fell back to deciding itself — which is the measurement the whole
+ * window-route change was made blind. No transcript, and not its length.
+ */
+ voice: (outcome: string, seconds: number, routed: string): ProductEvent => ({
+ name: 'dial_voice',
+ params: { outcome, seconds: Math.round(seconds), routed },
+ at: Date.now(),
+ }),
+
+ /**
+ * The carousel was walked. `kind` is `scroll`, `swipe` or `focus`.
+ *
+ * `ring_depth` is how far from the overview tile the dial ended up, which is
+ * the question behind the whole carousel: does anybody go past the first two
+ * agents, or is the ring a feature built for a walk nobody takes.
+ */
+ navigated: (kind: string, ringDepth: number): ProductEvent => ({
+ name: 'dial_navigated',
+ params: { kind, ring_depth: ringDepth },
+ at: Date.now(),
+ }),
+
+ /** The machine wheel was used at all. */
+ machineSelected: (): ProductEvent => ({
+ name: 'dial_machine_selected',
+ params: {},
+ at: Date.now(),
+ }),
+
+ /**
+ * An agent was opened on the dial. `source` is `dial` or `app_follow`.
+ *
+ * WHICH SCREEN LEADS. Two surfaces show the same agent and either can move the
+ * other; whether people drive from the dial or merely watch it follow the
+ * window is the question that decides what the dial is for.
+ */
+ agentOpened: (source: string): ProductEvent => ({
+ name: 'dial_agent_opened',
+ params: { source },
+ at: Date.now(),
+ }),
+
+ /** A question answered on the device rather than in the window. */
+ answer: (outcome: string): ProductEvent => ({
+ name: 'dial_answer',
+ params: { outcome },
+ at: Date.now(),
+ }),
+
+ /** A setting changed on the device — `brightness`, `scroll`, `language`. */
+ settingChanged: (setting: string): ProductEvent => ({
+ name: 'dial_setting_changed',
+ params: { setting },
+ at: Date.now(),
+ }),
+
+ /** An over-the-air update, and whether it landed. */
+ firmwareUpdate: (from: string, to: string, outcome: string): ProductEvent => ({
+ name: 'dial_fw_update',
+ params: { from, to, outcome },
+ at: Date.now(),
+ }),
+
+ /**
+ * Something went wrong on the device, as a short code.
+ *
+ * WORTH ITS OWN EVENT because of one open bug: the dial freezes — screen dead,
+ * touch dead, beeps still arriving — and after days of tracing there is still
+ * no cause, largely because there is no DATA. Every report is an anecdote. A
+ * code here, plus `detached`'s reason, turns it into a rate: how many dials,
+ * how often, at what firmware, after how long attached.
+ *
+ * It does not fix the bug. It makes it measurable, which is the step that has
+ * been missing.
+ */
+ fault: (code: string): ProductEvent => ({
+ name: 'dial_fault',
+ params: { code },
+ at: Date.now(),
+ }),
+}
+
+/** Names must be well-formed before anything is queued — see PRODUCT_EVENT_NAME. */
+export function isValidProductEvent(event: ProductEvent): boolean {
+ if (!PRODUCT_EVENT_NAME.test(event.name)) return false
+ if (!Number.isFinite(event.at) || event.at <= 0) return false
+ for (const value of Object.values(event.params)) {
+ const t = typeof value
+ if (t !== 'string' && t !== 'number' && t !== 'boolean') return false
+ if (t === 'number' && !Number.isFinite(value as number)) return false
+ }
+ return true
+}