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.

refactor: app presence automatically on local client registration instead of manual frames

0xken15e19ad3999c3d
diff --git a/backend/prisma/schema.prisma b/backend/prisma/schema.prisma
index 6c4649508..a3b0978b9 100644
--- a/backend/prisma/schema.prisma
+++ b/backend/prisma/schema.prisma
@@ -425,11 +425,11 @@ model AnalyticsMachineState {
/// src/lib/deviceWs.ts, adapter-ws in src/lib/adapterWs.ts).
/// Per-day record of whether a user had the desktop app open. One row per (user, UTC day). The
-/// source is the app's own `app_presence` ping to its local `harness` daemon, which the daemon
-/// forwards over adapter-ws (src/lib/adapterWs.ts) — NOT the web-ws upgrade, which the app never
-/// performs itself (only the daemon does, per foreign machine it relays) and which therefore missed
-/// every single-machine user. `connections` = times the app opened its local socket that day; a
-/// session spanning midnight produces a row for each day it touches with `connections: 0`.
+/// source is the local `harness` daemon reporting its own loopback clients over adapter-ws
+/// (`app_presence`, src/lib/adapterWs.ts) — NOT the web-ws upgrade, which the app never performs
+/// itself (only the daemon does, per foreign machine it relays) and which therefore missed every
+/// single-machine user. `connections` = times a window attached to the daemon that day; a session
+/// spanning midnight produces a row for each day it touches with `connections: 0`.
model UserDailyPresence {
id String @id @default(auto()) @map("_id") @db.ObjectId
userId String
diff --git a/backend/src/lib/adapterWs.ts b/backend/src/lib/adapterWs.ts
index 2d33c8c67..8deec89ef 100644
--- a/backend/src/lib/adapterWs.ts
+++ b/backend/src/lib/adapterWs.ts
@@ -82,10 +82,10 @@ 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
-// Daily presence of the PERSON (`user_daily_presence`): the desktop app pings its local daemon every
-// 30s while its loopback socket is up, the daemon forwards at most one `app_presence` up-frame a
-// minute, and this is the floor between two Mongo writes for the `ping` kind. `open` (the app just
-// connected its local socket) always writes — it is what `connections` counts. The web-ws upgrade
+// Daily presence of the PERSON (`user_daily_presence`): the daemon reports its own loopback clients —
+// `open` the moment a desktop window attaches, `ping` on its 15s app-ping tick while one stays, at
+// most once a minute (cli backendSocket sendAppPresence) — and this is the floor between two Mongo
+// writes for the `ping` kind. `open` always writes — it is what `connections` counts. The web-ws upgrade
// used to be the source, but the desktop app never dials web-ws directly (only the daemon does, and
// only to relay a foreign machine), so a single-machine user was invisible there.
const USER_PRESENCE_WRITE_MS = 5 * 60_000
@@ -408,9 +408,9 @@ async function attachAdapter(ws: WebSocket, machineId: string, userId: string, c
})
return
}
- // The desktop app's own presence ping, relayed by the daemon (cli localWsServer → backendSocket
- // sendAppPresence). Bookkeeping only — absorbed here, never published: no client has any use for
- // it and an unknown frame type must not reach the firmware.
+ // The daemon saying a desktop window is attached to it (cli backendSocket sendAppPresence).
+ // Bookkeeping only — absorbed here, never published: no client has any use for it and an
+ // unknown frame type must not reach the firmware.
if (app.type === 'app_presence') {
const kind = (app.payload as { kind?: unknown } | undefined)?.kind
if (typeof kind !== 'string' || !APP_PRESENCE_KINDS.has(kind)) return
diff --git a/backend/src/lib/dailyTracking.ts b/backend/src/lib/dailyTracking.ts
index 354e4fb87..ba76f97a9 100644
--- a/backend/src/lib/dailyTracking.ts
+++ b/backend/src/lib/dailyTracking.ts
@@ -18,10 +18,10 @@ import { prisma } from './prisma.js'
import { utcDayKey, utcDayStart } from '../types/analytics.js'
/**
- * Mark a user online for the UTC day containing `now`. The signal is the desktop app's own
- * `app_presence` ping, relayed by its local `harness` daemon over adapter-ws (src/lib/adapterWs.ts):
- * `isNewConnection: true` when the app just opened its loopback socket to the daemon (bumps
- * `connections`), `false` for the periodic ping (just touches `lastSeenAt`, at most every
+ * Mark a user online for the UTC day containing `now`. The signal is the `harness` daemon's
+ * `app_presence` frame over adapter-ws (src/lib/adapterWs.ts), sent about its own loopback clients:
+ * `isNewConnection: true` when a desktop window just attached to the daemon (bumps `connections`),
+ * `false` for the periodic ping while one stays attached (just touches `lastSeenAt`, at most every
* USER_PRESENCE_WRITE_MS). Not the web-ws upgrade — the app never dials that itself.
*
* `connections` counts app sessions OPENED on that day: a touch that is the first write of a new
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index fcc74386d..97ddfd133 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -990,31 +990,56 @@ describe('BackendSocket outbound queue', () => {
await socket.stop()
})
- it('forwards the window\'s presence: open at once, ping once a minute, nothing while offline', async () => {
+ it('reports the window itself: open when it attaches, ping once a minute while it stays, nothing while offline', async () => {
vi.useFakeTimers()
const socket = new BackendSocket('token')
- const presence = (ws: InstanceType<typeof wsMock.MockWebSocket>) => parseSent(ws)
+ const sink = { sendFrame: () => true, sendBinary: () => true }
+ const kinds = (ws: InstanceType<typeof wsMock.MockWebSocket>) => parseSent(ws)
.filter((m) => (m.frame as { type?: string } | undefined)?.type === 'app_presence')
+ .map((m) => (m.frame as { payload: { kind: string } }).payload.kind)
- // Signed out / not yet dialed: dropped, never queued behind real frames.
- expect(socket.sendAppPresence('open')).toBe(false)
+ // A window attaching to a not-yet-dialed daemon (the cold start): nothing can be sent yet, and
+ // nothing is queued behind real frames — but the session is owed to the link that comes up.
+ expect(socket.registerLocalClient('local:1', sink)).toBe(true)
socket.connect()
const ws = wsMock.instances[0]
- expect(socket.sendAppPresence('ping')).toBe(false)
+ expect(kinds(ws)).toEqual([])
ws.open()
- expect(ws.sent.filter((s) => s.includes('app_presence'))).toHaveLength(0)
-
- expect(socket.sendAppPresence('open')).toBe(true)
- // 30s later the window pings again — inside the floor, held back.
- vi.advanceTimersByTime(30_000)
- expect(socket.sendAppPresence('ping')).toBe(false)
- vi.advanceTimersByTime(30_000)
- expect(socket.sendAppPresence('ping')).toBe(true)
- // A second window opening is a session in its own right, floor or not.
- expect(socket.sendAppPresence('open')).toBe(true)
- expect(presence(ws).map((m) => (m.frame as { payload: { kind: string } }).payload.kind)).toEqual(['open', 'ping', 'open'])
+ expect(kinds(ws)).toEqual(['open'])
+
+ // While the window stays: once a minute on the app-ping tick, not once a tick.
+ vi.advanceTimersByTime(45_000)
+ expect(kinds(ws)).toEqual(['open'])
+ vi.advanceTimersByTime(15_000)
+ expect(kinds(ws)).toEqual(['open', 'ping'])
+
+ // A second window is a session in its own right — up at once, floor or not.
+ expect(socket.registerLocalClient('local:2', sink)).toBe(true)
+ expect(kinds(ws)).toEqual(['open', 'ping', 'open'])
+ // Registering the same window twice is refused, and says nothing.
+ expect(socket.registerLocalClient('local:2', sink)).toBe(false)
+ expect(kinds(ws)).toHaveLength(3)
+
+ // Every window gone: the tick falls silent.
+ await socket.unregisterLocalClient('local:1')
+ await socket.unregisterLocalClient('local:2')
+ vi.advanceTimersByTime(120_000)
+ expect(kinds(ws)).toHaveLength(3)
+
+ // A window that came and went while the link was down was never a session the backend can hear
+ // about — the next link is told nothing. Both remaining windows gone first, so the count is clean.
+ ws.close()
+ expect(socket.registerLocalClient('local:3', sink)).toBe(true)
+ await socket.unregisterLocalClient('local:3')
+ vi.advanceTimersByTime(60_000)
+ const ws2 = wsMock.instances[1]
+ ws2.open()
+ vi.advanceTimersByTime(15_000)
+ expect(kinds(ws2)).toEqual([])
+
// Bookkeeping about the person, for the backend alone: never fanned out to a client.
- expect(presence(ws)[0]).toMatchObject({ t: 'up', webEligible: false, commanderEligible: false })
+ expect(parseSent(ws).find((m) => (m.frame as { type?: string } | undefined)?.type === 'app_presence'))
+ .toMatchObject({ t: 'up', webEligible: false, commanderEligible: false })
await socket.stop()
})
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 846721aca..d6937acd5 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -103,9 +103,10 @@ export type RecentProvider = (sessionId: string, n: number) => Array<{ kind: str
const APP_PING_MS = 15_000
-// Floor between two `app_presence` up-frames. The window pings this daemon every 30s; the backend
-// only needs to hear about it about once a minute (it floors its own Mongo write at five). `open`
-// is never held back — it is the one that counts as a session in `user_daily_presence`.
+// Floor between two `app_presence` up-frames while a window is attached. Rides the 15s app-ping
+// tick; the backend only needs to hear about it about once a minute (it floors its own Mongo write
+// at five). `open` is never held back — it is the one that counts as a session in
+// `user_daily_presence`.
const APP_PRESENCE_UP_MS = 60_000
// How long the opening handshake may take before the attempt is abandoned and retried. `ws` waits
// forever by default, and the heartbeat below only starts on 'open' — so a TCP connection that came
@@ -311,6 +312,10 @@ export class BackendSocket {
private heartbeat: LivenessWatch | null = null
private appPing: NodeJS.Timeout | null = null
private lastAppPresenceUpAt = 0
+ // A window attached while there was no link to tell (cold start: the app dials this daemon before
+ // the daemon has dialed the backend; or a daemon restart under an open window). The session is
+ // real and must be counted once, so it is owed to the next link — not turned into a `ping`.
+ private appOpenOwed = false
private readonly downChains = new Map<string, Promise<void>>()
private readonly localClients = new Map<string, LocalClientSink>()
private terminalStreams: TerminalStreamManager | null = null
@@ -608,10 +613,14 @@ export class BackendSocket {
onIdle: (idleMs) => console.log(`[backend] no traffic for ${Math.round(idleMs / 1000)}s — terminating the link`),
})
- // App-level ping refreshes the backend's presence key (TTL 30s).
- this.appPing = setInterval(() => this.sendBestEffort({ t: 'ping' }), APP_PING_MS)
- // A fresh socket knows nothing about the window; let its next ping through at once.
+ // App-level ping refreshes the backend's presence key (TTL 30s). The window's presence rides
+ // the same tick — a fresh socket knows nothing about the window, so its first tick goes through.
this.lastAppPresenceUpAt = 0
+ if (this.appOpenOwed && this.localClients.size > 0) this.sendAppPresence('open')
+ this.appPing = setInterval(() => {
+ this.sendBestEffort({ t: 'ping' })
+ if (this.localClients.size > 0) this.sendAppPresence('ping')
+ }, APP_PING_MS)
})
ws.on('message', (raw, isBinary) => {
@@ -827,11 +836,13 @@ export class BackendSocket {
}
/**
- * The desktop window is open on this computer (localWsServer `app_presence`): tell the backend, which
- * turns it into the person's `user_daily_presence` row. `open` goes up at once, `ping` at most once
- * per APP_PRESENCE_UP_MS. Best-effort and plaintext on purpose: it is bookkeeping about the person,
- * not data, and a daemon that is signed out (no backend dial) or between reconnects simply drops it
- * rather than queueing a stale "was open" behind real frames. Returns whether a frame went up.
+ * The desktop window is open on this computer: tell the backend, which turns it into the person's
+ * `user_daily_presence` row. The window itself says nothing — its loopback socket IS the fact, so
+ * this daemon reports it: `open` the moment a window registers (registerLocalClient), `ping` on the
+ * app-ping tick while any window is attached, at most once per APP_PRESENCE_UP_MS. Best-effort and
+ * plaintext on purpose: it is bookkeeping about the person, not data, and a daemon that is signed
+ * out (no backend dial) or between reconnects simply drops it rather than queueing a stale "was
+ * open" behind real frames. Returns whether a frame went up.
*/
sendAppPresence(kind: 'open' | 'ping'): boolean {
const now = Date.now()
@@ -843,6 +854,7 @@ export class BackendSocket {
frame: { type: 'app_presence', payload: { kind } },
})
if (sent) this.lastAppPresenceUpAt = now
+ if (kind === 'open') this.appOpenOwed = !sent
return sent
}
@@ -850,12 +862,16 @@ export class BackendSocket {
registerLocalClient(connId: string, sink: LocalClientSink): boolean {
if (!isLocalClientId(connId) || this.localClients.has(connId)) return false
this.localClients.set(connId, sink)
+ this.sendAppPresence('open')
return true
}
/** Release all connection-scoped state when the loopback WebSocket closes. */
async unregisterLocalClient(connId: string): Promise<void> {
if (!this.localClients.delete(connId)) return
+ // The window left before any link could hear it attach: nothing happened, as far as the backend
+ // is concerned, and a later link must not be told otherwise.
+ if (this.localClients.size === 0) this.appOpenOwed = false
this.downChains.delete(connId)
await this.terminalStreams?.closeConnection(connId, 'local client disconnected', false)
}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index ad02cd895..01022c122 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -3217,9 +3217,6 @@ async function runForeground(session: AuthSession): Promise<void> {
// The window's swarms. Relayed to the dial as its own list — the dial names the one on screen above
// the agent and offers the rest — and, through setSwarms, what makes the desk strict: a present
// window with an empty swarm is an empty carousel, not the whole machine.
- // The window's "I am open" — the only desk fact that goes UP. Throttled and dropped-when-offline
- // inside sendAppPresence, so a guest daemon costs nothing here.
- onAppPresence: (kind) => { backend.sendAppPresence(kind) },
onAppSwarms: (swarms) => {
cableHostRef?.setSwarms(swarms)
void cableRef?.syncSwarms()
diff --git a/cli/src/localWsServer.ts b/cli/src/localWsServer.ts
index 236cb6bc5..345745070 100644
--- a/cli/src/localWsServer.ts
+++ b/cli/src/localWsServer.ts
@@ -33,8 +33,6 @@ export interface LocalWsBackend {
handleLocalBinary: (connId: string, frame: TerminalBinaryClear) => Promise<void>
}
-export type AppPresenceKind = 'open' | 'ping'
-
export interface LocalWsServerOptions {
machineId: string
backend: LocalWsBackend
@@ -49,12 +47,6 @@ export interface LocalWsServerOptions {
onAppFocus?: (machineId: string, agentId: string) => void
/** Every agent the window currently has a tile for, across all its machines. */
onAppPanes?: (agentIds: string[]) => void
- /**
- * The window is open: `open` once when it connects this socket, `ping` every 30s after. The one fact
- * about this desk the backend does want (it is how a person's day gets counted, see backendSocket
- * sendAppPresence) — so it is the daemon's to forward, throttled, and never the machine's to see.
- */
- onAppPresence?: (kind: AppPresenceKind) => void
/**
* The window's swarms — its named groups of agents, one of them on screen. The whole list each time,
* and `null` when the window goes away, so the daemon never keeps describing tabs nobody can see.
@@ -421,13 +413,6 @@ export function attachLocalWsServer(server: http.Server, options: LocalWsServerO
// Focus is local desk state and must never be forwarded to a remote machine.
return
}
- if (parsed?.type === 'app_presence') {
- const kind = (parsed.payload as Record<string, unknown> | undefined)?.kind
- if (kind === 'open' || kind === 'ping') options.onAppPresence?.(kind)
- // Like app_focus: about this desk, never the machine's business — a remote daemon would
- // only drop it as an unknown frame anyway.
- return
- }
// Preserve the old dial fallback; terminal streams never establish voice focus.
if (parsed?.type === 'terminal_open' && typeof agentId === 'string' && agentId) {
options.onAppFocus?.(boundMachineId, agentId)