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.

9.4 KB
Raw Blame
/** 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 })
  }
}