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(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.tsindex 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) => voidmachineName: () => 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.tsindex 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 = 10const 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 = nullprivate greetedMac: string | null = nullprivate 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 = 0private 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 = 0private 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 = 0private opening = falseprivate 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)returncase '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') ?? '')returncase 'models.list': {@@ -735,6 +838,10 @@ export class CableSession {}returncase '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')!)returncase 'scroll': {@@ -745,10 +852,20 @@ export class CableSession {if (phase !== 'down' && phase !== 'move' && phase !== 'up') returnconst dy = typeof msg.dy === 'number' ? msg.dy : 0const 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')!)returncase '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'))returncase '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.versionthis.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) returnthis.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) returnif (!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.appFocusGenerationconst 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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+}