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: track daily agent and machine turn counts from websocket turn_started frames

0xken15c818adc581ab
diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prisma
index a4be87f6e..0991ac895 100644
--- a/backend/prisma/schema.prisma
+++ b/backend/prisma/schema.prisma
@@ -482,18 +482,45 @@ model UserDailyDevicePresence {
/// row for each day it touches. `lastSeenAt` is refreshed on connect, on close, and at most every
/// MACHINE_PRESENCE_WRITE_MS while the socket is open, so it lags real liveness by ≤ that interval.
/// Redis `machine:{id}:mgr` remains the "online right now" answer; this is the history.
+/// `turnsStarted` is the usage signal on top of liveness: every `turn_started` up-frame the daemon
+/// relays bumps it (adapterWs hub tap). A row can legitimately read `connections: 0, turnsStarted: 0`
+/// — a session that spanned midnight and sat idle.
model MachineDailyPresence {
- id String @id @default(auto()) @map("_id") @db.ObjectId
- machineId String // Machine.machineId
- userId String // owner at connect time (Machine.userId), for per-user rollups
- dayUtc DateTime
- connections Int @default(0)
- firstSeenAt DateTime
- lastSeenAt DateTime
- createdAt DateTime @default(now())
- updatedAt DateTime @updatedAt
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ machineId String // Machine.machineId
+ userId String // owner at connect time (Machine.userId), for per-user rollups
+ dayUtc DateTime
+ connections Int @default(0)
+ turnsStarted Int @default(0) // `turn_started` up-frames the daemon sent that day (adapterWs tap)
+ firstSeenAt DateTime
+ lastSeenAt DateTime
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
@@unique([machineId, dayUtc])
@@index([userId, dayUtc])
@@map("machine_daily_presence")
}
+
+/// Per-day record of an AGENT being driven: one row per (machine, agent, UTC day), created and
+/// bumped by every `turn_started` the machine's daemon relays through adapter-ws
+/// (src/lib/adapterWs.ts). There is no "connect" for an agent — a turn is the presence signal —
+/// so unlike the machine/user/device rows there is no `connections` column. `agentId` is the
+/// plaintext correlation id on the frame; the turn's content stays E2EE and is never read here.
+model AgentDailyPresence {
+ id String @id @default(auto()) @map("_id") @db.ObjectId
+ machineId String // Machine.machineId — agentId is only unique within a machine
+ agentId String // MachineAgent.agentId (may be gone from machine_agents later — keep the history)
+ userId String // owner at the time of the turn
+ dayUtc DateTime
+ turnsStarted Int @default(0)
+ firstSeenAt DateTime
+ lastSeenAt DateTime
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+
+ @@unique([machineId, agentId, dayUtc])
+ @@index([machineId, dayUtc])
+ @@index([userId, dayUtc])
+ @@map("agent_daily_presence")
+}
diff --git a/backend/src/lib/adapterWs.ts b/backend/src/lib/adapterWs.ts
index 69192b01f..70b5b9041 100644
--- a/backend/src/lib/adapterWs.ts
+++ b/backend/src/lib/adapterWs.ts
@@ -25,7 +25,7 @@ import {
import { trackSocketLiveness } from './hub.js'
import { guardedSend, guardedSendJson } from './wsSend.js'
import { attachNodeRole, PRESENCE_TTL_SEC } from './nodeRole.js'
-import { presenceWriteDue, touchMachineOnlineDay, type PresenceWriteState } from './dailyTracking.js'
+import { presenceWriteDue, recordTurnStarted, touchMachineOnlineDay, type PresenceWriteState } from './dailyTracking.js'
import { recordCreatedAgent, recordDeletedAgent } from './agentTracker.js'
import type { Frame } from './tunnel.js'
import { logger } from '../utils/logger.js'
@@ -82,6 +82,16 @@ const CLIENT_VERSION_RE = /^[A-Za-z0-9._+-]{1,64}$/
// day costs ~300 upserts, not ~6000. Connect and close always write regardless.
const MACHINE_PRESENCE_WRITE_MS = 5 * 60_000
+// `turn_started` tap (agent/machine daily presence). `agentId` is a plain token the CLI derives from
+// its registry (a UUID, or the engine's own session id as fallback), so it is bounded and
+// character-restricted before it becomes a Mongo index key — an oversized or exotic value would
+// otherwise either fail the unique index (>1024-byte key) or let a misbehaving adapter mint an
+// unbounded number of `agent_daily_presence` rows. The per-minute cap is the same idea for volume:
+// a real turn is human-paced (a handful a minute across every agent on one machine), so anything
+// past this is a bug or abuse and is dropped, never written.
+const TURN_AGENT_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/
+const TURN_WRITES_PER_MINUTE = 120
+
function sanitizeClientVersion(raw: string | null): string | undefined {
const v = raw?.trim()
return v && CLIENT_VERSION_RE.test(v) ? v : undefined
@@ -184,6 +194,13 @@ async function attachAdapter(ws: WebSocket, machineId: string, userId: string, c
// starts with no claim and must re-assert, so a fresh value can never renew a stale one.
let appState: { engine: string; state: string } | undefined
const terminalRate = new TerminalRateGuard()
+ // Fixed one-minute window for the `turn_started` tap — two integers, no timer, no allocation.
+ let turnWindowStart = 0
+ let turnWindowCount = 0
+ const allowTurnWrite = (nowMs: number): boolean => {
+ if (nowMs - turnWindowStart >= 60_000) { turnWindowStart = nowMs; turnWindowCount = 0 }
+ return ++turnWindowCount <= TURN_WRITES_PER_MINUTE
+ }
const p2pSignalRate = new P2pSignalRateGuard()
// Buffer messages from RIGHT NOW, because the real handler cannot be installed until after the
@@ -361,7 +378,7 @@ async function attachAdapter(ws: WebSocket, machineId: string, userId: string, c
// Hub tap (mirrors managerWs): keep `machine_agents` in sync from the adapter's agent
// lifecycle frames. Needed so the device voice path's agent-ownership check
// (deviceWs: `machineAgent.findFirst`) recognizes remote tmux sessions.
- const f = env.frame as { type?: string; payload?: { agent?: unknown; agentId?: unknown; machineId?: unknown } }
+ const f = env.frame as { type?: string; agentId?: unknown; payload?: { agent?: unknown; agentId?: unknown; machineId?: unknown } }
if (f.type === 'agent_synced') {
void recordCreatedAgent(machineId, f.payload?.agent as { id?: unknown; name?: unknown } | undefined)
} else if (f.type === 'agent_deleted' && typeof f.payload?.agentId === 'string') {
@@ -369,6 +386,20 @@ async function attachAdapter(ws: WebSocket, machineId: string, userId: string, c
// Reading `machineId` here meant no deletion was EVER recorded, so machine_agents grew a row per
// agent forever — and that table is what the plan cap counts.
void recordDeletedAgent(machineId, f.payload.agentId)
+ } else if (f.type === 'turn_started') {
+ // Usage signal for machine_daily_presence / agent_daily_presence. Only the plaintext `type`
+ // and top-level `agentId` (set by the CLI's correlateAgentEvent) are read — the payload is
+ // E2EE ciphertext (cli e2ee/core.ts ENCRYPTED_UP_TYPES) and stays opaque here. The CLI already
+ // dedupes engines that re-announce one turn (cursor/agy/copilot, cli.ts), so one frame == one
+ // turn; the one known over-count is a daemon restarting mid-turn, which re-emits the open
+ // turn's start on attach (cli.ts `resumed`) — rare, and invisible from here. A frame with no
+ // (or a malformed) agentId has nothing to attribute the turn to and is not counted.
+ const now = new Date()
+ const agentId = typeof f.agentId === 'string' && TURN_AGENT_ID_RE.test(f.agentId) ? f.agentId : undefined
+ if (agentId && allowTurnWrite(now.getTime())) {
+ void recordTurnStarted(userId, machineId, agentId, now)
+ .catch((err) => logger.warn('turn tracking failed', { machineId, agentId, error: String(err) }))
+ }
}
if (env.userEligible) {
void publishUserDeviceE2eePair(userId, machineId, env.frame).catch((err) => {
diff --git a/backend/src/lib/dailyTracking.test.ts b/backend/src/lib/dailyTracking.test.ts
index 62b0e3649..1fb334ae4 100644
--- a/backend/src/lib/dailyTracking.test.ts
+++ b/backend/src/lib/dailyTracking.test.ts
@@ -2,15 +2,17 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
const db = vi.hoisted(() => ({
machinePresenceUpsert: vi.fn(),
+ agentPresenceUpsert: vi.fn(),
}))
vi.mock('./prisma.js', () => ({
prisma: {
machineDailyPresence: { upsert: db.machinePresenceUpsert },
+ agentDailyPresence: { upsert: db.agentPresenceUpsert },
},
}))
-import { presenceWriteDue, touchMachineOnlineDay } from './dailyTracking.js'
+import { presenceWriteDue, recordTurnStarted, touchMachineOnlineDay } from './dailyTracking.js'
import { utcDayStart } from '../types/analytics.js'
describe('touchMachineOnlineDay', () => {
@@ -52,6 +54,51 @@ describe('touchMachineOnlineDay', () => {
})
})
+describe('recordTurnStarted', () => {
+ const now = new Date('2026-09-16T10:15:30.000Z')
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ db.machinePresenceUpsert.mockResolvedValue({})
+ db.agentPresenceUpsert.mockResolvedValue({})
+ })
+
+ it('bumps turnsStarted on the machine row without counting a connection', async () => {
+ await recordTurnStarted('user-1', 'machine-a', 'agent-x', now)
+
+ expect(db.machinePresenceUpsert).toHaveBeenCalledTimes(1)
+ const call = db.machinePresenceUpsert.mock.calls[0][0]
+ expect(call.where).toEqual({ machineId_dayUtc: { machineId: 'machine-a', dayUtc: utcDayStart(now) } })
+ expect(call.create).toEqual({
+ machineId: 'machine-a', userId: 'user-1', dayUtc: utcDayStart(now),
+ connections: 0, turnsStarted: 1, firstSeenAt: now, lastSeenAt: now,
+ })
+ expect(call.update).toEqual({ lastSeenAt: now, turnsStarted: { increment: 1 } })
+ })
+
+ it('bumps the (machine, agent, day) row', async () => {
+ await recordTurnStarted('user-1', 'machine-a', 'agent-x', now)
+
+ expect(db.agentPresenceUpsert).toHaveBeenCalledTimes(1)
+ const call = db.agentPresenceUpsert.mock.calls[0][0]
+ expect(call.where).toEqual({
+ machineId_agentId_dayUtc: { machineId: 'machine-a', agentId: 'agent-x', dayUtc: utcDayStart(now) },
+ })
+ expect(call.create).toEqual({
+ machineId: 'machine-a', agentId: 'agent-x', userId: 'user-1', dayUtc: utcDayStart(now),
+ turnsStarted: 1, firstSeenAt: now, lastSeenAt: now,
+ })
+ expect(call.update).toEqual({ lastSeenAt: now, turnsStarted: { increment: 1 } })
+ })
+
+ it('propagates a failure from either upsert', async () => {
+ db.agentPresenceUpsert.mockRejectedValueOnce(new Error('agent row failed'))
+ await expect(recordTurnStarted('user-1', 'machine-a', 'agent-x', now)).rejects.toThrow('agent row failed')
+ // The machine write was still attempted — the two are independent.
+ expect(db.machinePresenceUpsert).toHaveBeenCalledTimes(1)
+ })
+})
+
describe('presenceWriteDue', () => {
const FIVE_MIN = 5 * 60_000
const t0 = new Date('2026-09-16T10:00:00.000Z')
diff --git a/backend/src/lib/dailyTracking.ts b/backend/src/lib/dailyTracking.ts
index 375d26869..a0d02252f 100644
--- a/backend/src/lib/dailyTracking.ts
+++ b/backend/src/lib/dailyTracking.ts
@@ -1,10 +1,10 @@
/**
* Presence / remote-usage daily tracking — write path for `UserDailyPresence`,
- * `UserDailyRemoteUsage`, `UserDailyDevicePresence` and `MachineDailyPresence`
- * (prisma/schema.prisma). Separate model family and separate module from the opt-in `Analytics*`
- * telemetry in analyticsIngest.ts: these signals are derived directly from the web-ws/device-ws/
- * adapter-ws relays (src/lib/webWs.ts, src/lib/deviceWs.ts, src/lib/adapterWs.ts), not from a
- * collector upload.
+ * `UserDailyRemoteUsage`, `UserDailyDevicePresence`, `MachineDailyPresence` and
+ * `AgentDailyPresence` (prisma/schema.prisma). Separate model family and separate module from the
+ * opt-in `Analytics*` telemetry in analyticsIngest.ts: these signals are derived directly from the
+ * web-ws/device-ws/adapter-ws relays (src/lib/webWs.ts, src/lib/deviceWs.ts, src/lib/adapterWs.ts),
+ * not from a collector upload.
*
* Unlike analyticsIngest.ts, none of these rows need last-write-wins ordering (there's no
* client-supplied revision to defend against), so each touch is a plain atomic `upsert` on the
@@ -99,6 +99,34 @@ export async function touchMachineOnlineDay(
})
}
+/**
+ * Count one `turn_started` the machine's daemon reported for `agentId` on the UTC day containing
+ * `now`: bumps the machine row's `turnsStarted` and the (machine, agent) row. Both also touch
+ * `lastSeenAt` — a turn is the strongest liveness signal there is. The two upserts are independent
+ * atomic `$inc`s, deliberately not a transaction: a partial failure under-counts one row by one and
+ * the caller's warn log says so, which beats a transaction retry loop on the relay's hot path.
+ */
+export async function recordTurnStarted(
+ userId: string,
+ machineId: string,
+ agentId: string,
+ now: Date,
+): Promise<void> {
+ const dayUtc = utcDayStart(now)
+ await Promise.all([
+ prisma.machineDailyPresence.upsert({
+ where: { machineId_dayUtc: { machineId, dayUtc } },
+ create: { machineId, userId, dayUtc, connections: 0, turnsStarted: 1, firstSeenAt: now, lastSeenAt: now },
+ update: { lastSeenAt: now, turnsStarted: { increment: 1 } },
+ }),
+ prisma.agentDailyPresence.upsert({
+ where: { machineId_agentId_dayUtc: { machineId, agentId, dayUtc } },
+ create: { machineId, agentId, userId, dayUtc, turnsStarted: 1, firstSeenAt: now, lastSeenAt: now },
+ update: { lastSeenAt: now, turnsStarted: { increment: 1 } },
+ }),
+ ])
+}
+
/** Last SUCCESSFUL presence write for one open socket — `dayKey` null until the first one lands. */
export interface PresenceWriteState { dayKey: string | null; wroteAt: number }