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
/** Relay signals contribute daily fleet totals and, while sharing is on, a person's 10-day activity
* mark (lib/productUsage.ts markActivity). Operational live presence stays in Redis.
* No machine, agent or device history is written here: the one machine fact kept is the overwritten
* `machines.lastSeenAt`. Older row types remain readable during their bounded expiry window; their
* historical metrics must not be mixed with these totals.
*/
import { utcDayKey } from '../types/analytics.js'
import { releaseBucket } from '../types/productHealthContract.js'
import { markActivity, recordRelayUsage, type RelayUsageMetric } from './productUsage.js'
import { prisma } from './prisma.js'
import { logger } from '../utils/logger.js'
export interface PresenceTouchOpts { isNewConnection: boolean; countryCode?: string }
export async function touchUserOnlineDay(userId: string, _machineId: string, now: Date, opts: { isNewConnection: boolean }): Promise<void> {
// The person is active today whether this is an open or a ping; only opens add a relay total.
void markActivity(userId, now, { surface: 'desktop' }).catch(() => {})
if (opts.isNewConnection) await recordRelayUsage(userId, now, 'relay_desktop_opens')
}
export async function recordRemoteUsage(userId: string, _machineId: string, now: Date): Promise<void> {
await recordRelayUsage(userId, now, 'relay_remote_sessions')
}
export async function touchDeviceOnlineDay(userId: string, _deviceId: string, now: Date, opts: PresenceTouchOpts): Promise<void> {
if (opts.isNewConnection) await recordRelayUsage(userId, now, 'relay_device_connections')
}
/** The connection facts an adapter connect reports (lib/adapterWs.ts), each a `machines` field. */
export type MachineConnectChanges = Partial<Record<'hostname' | 'name' | 'clientVersion' | 'computerId' | 'countryCode' | 'sessionKind', string>>
/** Those fields as the upgrade read them from the row. */
export type MachineConnectRow = { [K in keyof MachineConnectChanges]?: string | null }
/** The facts of `next` that differ from `row`: a connect rewrites only what changed (Ken's prod scan of 11-04, #2676:
* every reconnect rewrote the same host, version and computer). A fact the connect did not send is left as it is. */
export function machineConnectChanges(row: MachineConnectRow, next: MachineConnectChanges): MachineConnectChanges {
const changes: MachineConnectChanges = {}
for (const [key, value] of Object.entries(next) as Array<[keyof MachineConnectChanges, string | undefined]>) {
if (value !== undefined && row[key] !== value) changes[key] = value
}
return changes
}
/** A row's `lastSeenAt` as a socket's write state: a new socket floors its stamps on the row's last stamp, so a
* reconnect a minute after the last one does not stamp again. A row never stamped is due at once. */
export function presenceStateFromRow(lastSeenAt: Date | null | undefined): PresenceWriteState {
return lastSeenAt ? { dayKey: utcDayKey(lastSeenAt), wroteAt: lastSeenAt.getTime() } : { dayKey: null, wroteAt: 0 }
}
export interface MachineTouchOpts extends PresenceTouchOpts {
/** Connection facts that changed, written in the same update as the stamp. */
changes?: MachineConnectChanges
/** false when the row's stamp is not due: only `changes` are written. */
stamp?: boolean
}
/** One update of the machine's row: the changed facts and its `lastSeenAt` (the caller floors it), none when both are
* empty; and a connect's total. Both start together, so a failed total never costs the stamp; either failure rejects,
* so the caller's floor does not advance and its next heartbeat retries. */
export async function touchMachineOnlineDay(userId: string, machineId: string, now: Date, opts: MachineTouchOpts): Promise<void> {
const data = { ...opts.changes, ...(opts.stamp === false ? {} : { lastSeenAt: now }) }
await Promise.all([
Object.keys(data).length ? prisma.machine.update({ where: { machineId }, data }) : undefined,
opts.isNewConnection ? recordRelayUsage(userId, now, 'relay_machine_connections') : undefined,
])
}
/** Which daily mark a turn sets: `worked` is only the person's own sessions' turns; a Swarm agent's turn on their Mac is
* `hosting` (Dee, 2026-11-04). A Swarm agent is found by its machine and current terminal, not its id: a rebound one keeps
* the id of its first terminal (superTabs/commands.ts agent.rebind). A removed one, or a terminal one left, is only the
* owner's session now. A Team account runs only Swarm agents, so its turns read nothing. */
export async function turnMark(machineId: string, agentId: string, team: boolean): Promise<{ worked: true } | { hosting: true }> {
if (team) return { hosting: true }
// A plain $match: Prisma has no filter inside `data`. Reads only this machine's live agents ([machineId, deleted]).
const rows = await prisma.swarmAgent.aggregateRaw({ pipeline: [{ $match: { machineId, deleted: false, 'data.harnessId': agentId } }, { $limit: 1 }, { $project: { _id: 1 } }] }) as unknown as unknown[]
return rows.length ? { hosting: true } : { worked: true }
}
export async function recordTurnStarted(userId: string, machineId: string, agentId: string, now: Date, team = false): Promise<void> {
// Started together: a failed read costs this turn's mark, never its total. Neither mark when it cannot tell whose turn it is.
await Promise.all([
turnMark(machineId, agentId, team).then(mark => markActivity(userId, now, mark))
.catch(err => logger.warn('turn mark skipped: could not read whose turn it is; this turn counts in no person\'s day', { error: String(err) })),
recordRelayUsage(userId, now, 'relay_turns_started'),
])
}
/** Last SUCCESSFUL presence write for one open socket — `dayKey` null until the first one lands. */
export interface PresenceWriteState { dayKey: string | null; wroteAt: number }
/**
* Whether a heartbeat on an open socket should write presence now: yes when nothing has been
* written yet, when the UTC day rolled over since the last write (so the new day gets its row),
* or when the last write is at least `minIntervalMs` old. Lets a caller ride an existing
* high-frequency tick (15s node heartbeat) without writing Mongo at that rate.
*/
export function presenceWriteDue(last: PresenceWriteState, now: Date, minIntervalMs: number): boolean {
if (last.dayKey === null) return true
if (utcDayKey(now) !== last.dayKey) return true
return now.getTime() - last.wroteAt >= minIntervalMs
}
/** Relay surfaces with separate connection totals, never distinct-person counts. */
export type ClientSurface = 'tui' | 'harness-os' | 'harness-os-pi' | 'mobile' | 'web'
export const CLIENT_SURFACES: ReadonlySet<string> = new Set<ClientSurface>(['tui', 'harness-os', 'harness-os-pi', 'mobile', 'web'])
/** Known terminal surfaces retain their platform distinction in fleet connection totals. */
export const TUI_SURFACES: ReadonlySet<string> = new Set<ClientSurface>(['tui', 'harness-os', 'harness-os-pi'])
/** What the phone says of the build that opened a socket (`?release=` and `?debug=1`, webWs.ts). */
export interface ClientBuild { release?: string | null; debug?: boolean }
/** What a phone open adds beside `relay_mobile_opens`, which still counts every one of them: a debug or
* simulator build's open under `relay_mobile_debug_opens`, any other under its release's margin, the way
* phone reports split by release (`breakdown:release:phone:<release>:`). The release is the public
* x.y.z only; an older app that sends none, or anything else, is `unknown`. The two never overlap, so a
* simulator left open cannot pass for a release. */
export function mobileOpenMetrics(build: ClientBuild = {}): RelayUsageMetric[] {
return [build.debug === true ? 'relay_mobile_debug_opens'
: `breakdown:release:phone:${releaseBucket(build.release)}:relay_mobile_opens`]
}
/** Keep old protocol entry points while reducing only new connection events into fleet totals. */
export async function touchClientOnlineDay(
userId: string, surface: ClientSurface, now: Date, opts: { isNewConnection: boolean; build?: ClientBuild },
): Promise<void> {
void markActivity(userId, now, { surface }).catch(() => {})
if (!opts.isNewConnection) return
if (surface === 'mobile') await recordRelayUsage(userId, now, 'relay_mobile_opens', mobileOpenMetrics(opts.build))
else await recordRelayUsage(userId, now, `relay_${surface}_opens`)
}
/**
* The legacy protocol's cadence: `open` counts an event at most once per `openFloorMs`, so a reconnect
* storm is not a hundred sessions. `ping` is still throttled but its callback no longer stores history.
* `write` gets `isNewConnection`; failures go to `onError` — callers never await this.
*/
export function presenceTracker(
write: (now: Date, isNewConnection: boolean) => Promise<void>,
onError: (kind: 'open' | 'ping', err: unknown) => void,
{ pingFloorMs, openFloorMs }: { pingFloorMs: number; openFloorMs: number },
): (kind: 'open' | 'ping') => void {
const last: PresenceWriteState = { dayKey: null, wroteAt: 0 }
let inFlight = false
let lastOpenAt = 0
return (kind) => {
const now = new Date()
if (kind === 'ping' && (inFlight || !presenceWriteDue(last, now, pingFloorMs))) return
if (kind === 'open') {
if (now.getTime() - lastOpenAt < openFloorMs) return
lastOpenAt = now.getTime()
}
inFlight = true
write(now, kind === 'open')
.then(() => { last.dayKey = utcDayKey(now); last.wroteAt = now.getTime() })
.catch((err) => onError(kind, err))
.finally(() => { inFlight = false })
}
}