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.

8.0 KB
Raw Blame
/**
 * What a machine's Swarms want of its host, read as the host form (design 2026-10-26-swarm-state-parts section 4.10): for
 * each Swarm its roster rows, its pool of this machine and the assignments running here. It replaces the three rosters the
 * host, the machine pass and the GitHub tokens each read on their own, every one loading up to 100 whole Swarms every 1–5 s.
 * In between, only the Swarms with a change that matters to this machine come back; a full read at start and at least every
 * minute also catches a share or billing change, which lives outside the parts.
 */
import type { BackendNotice, CoreApi } from '../core/api.js'
import type { HostChanges, HostChangesRequest, HostTabRows } from './readContract.js'
import { backend, object, readable } from './wire.js'

type Json = Record<string, unknown>
export interface HostRead { roster: Json[]; pools: Json[]; assignments: Json[] }

/** The bound on a roster that lags a revoked share (design section 8, Q2), and on one that missed a push. */
export const HOST_FULL_MS = 60_000
/** WS roadmap Phase 2a: a server that pushes (backend lib/swarmHostPushes.ts) says so every 4 minutes, through Redis like the
 *  pushes themselves. Without that word for this long (an older server, a rollback, Redis gone silent) the host reads each
 *  second again. */
export const HOST_PUSH_LEASE_MS = 5 * 60_000
/** Told many times in a second, by a busy Swarm, the host still reads at most once a second, as it did before pushes. */
export const HOST_PUSH_GAP_MS = 1_000

/** The server's word over the daemon socket: a Swarm to read, or, naming none, that it pushes. */
type HostNotice = Extract<BackendNotice, { type: 'swarm_host_changed' }>

export class HostFeed {
  private readonly now: () => number
  private readonly backend: typeof backend
  /** Each Swarm's rows as last returned, in the order the server first listed them. */
  private tabs = new Map<string, HostTabRows>()
  private cursor: string | null = null
  private fullAt = -Infinity
  private readAt = -Infinity
  private running: Promise<HostRead> | null = null
  /** Until when the server is known to push (HOST_PUSH_LEASE_MS); a new feed, as after a reconnect, starts without it. */
  private pushUntil = -Infinity
  /** Told of a change since the last read began. */
  private told = false
  /** Told of every read the feed makes ([watch]). */
  private readonly watchers = new Set<(read: HostRead) => void>()

  constructor(private readonly core: CoreApi, readonly machineId: string, options: { now?: () => number; backend?: typeof backend } = {}) {
    this.now = options.now ?? Date.now
    this.backend = options.backend ?? backend
  }

  /** One read at a time: callers that ask while it runs get its answer. */
  refresh(): Promise<HostRead> {
    return this.running ??= this.read().finally(() => { this.running = null })
  }

  /** A read sent after this call. One already out may have been sent before what the caller must see, such as a takeover
   *  before a resume's answer (cli limitResume.ts, #1757 re-check), so it is waited out, never joined. */
  async fresh(): Promise<HostRead> {
    await this.running?.catch(() => {})
    return this.refresh()
  }

  /** [watcher] is told of each read this feed makes, once it is held; returns what stops it. A watcher that throws is
   *  passed over: it never fails the read. */
  watch(watcher: (read: HostRead) => void): () => void {
    this.watchers.add(watcher)
    return () => { this.watchers.delete(watcher) }
  }

  /** Whether the server pushes: its last word that it does is under HOST_PUSH_LEASE_MS old. */
  get pushing(): boolean { return this.now() < this.pushUntil }

  /** The server said a Swarm of this machine changed, or (naming none) that it pushes: the next due read reads. */
  heard(notice: HostNotice): void {
    if (typeof notice.tabId !== 'string') this.pushUntil = this.now() + HOST_PUSH_LEASE_MS
    this.told = true
  }

  /** The host's one-second tick: a read each second, unless the server pushes; then one when told, at most once a second,
   *  and the full read a minute after the last, the safety net for a push lost on the way. */
  due(): Promise<HostRead> {
    return this.running || this.readsNow ? this.refresh() : Promise.resolve(this.snapshot())
  }

  /** Whether [due] would send a read now, not counting one already out: the host starts a pass for a push only then, since
   *  every pass reads each busy agent's delivery list again (review of #2113: 5 pushes in 250 ms were 5 list reads). */
  get readsNow(): boolean {
    if (this.running) return false
    if (!this.pushing || this.cursor === null) return true
    const now = this.now()
    return (this.told && now - this.readAt >= HOST_PUSH_GAP_MS) || now - this.fullAt >= HOST_FULL_MS
  }

  /** The last read while it is at most `maxAgeMs` old, else a new one: for readers off the host's own one-second tick. While
   *  the server pushes, the last read stands until told or until the minute's full read is due. */
  current(maxAgeMs: number): Promise<HostRead> {
    const now = this.now()
    const fresh = this.pushing ? this.cursor !== null && !this.told && now - this.fullAt < HOST_FULL_MS : now - this.readAt < maxAgeMs
    if (!this.running && fresh) return Promise.resolve(this.snapshot())
    return this.refresh()
  }

  private async read(): Promise<HostRead> {
    // Taken as the read starts: a push heard while it is out may name a change it missed, so the next one reads again.
    const told = this.told
    this.told = false
    try { return await this.ask() } catch (error) { this.told ||= told; throw error }
  }

  private async ask(): Promise<HostRead> {
    const askFull = this.cursor === null || this.now() - this.fullAt >= HOST_FULL_MS
    const startedAt = this.now()
    const form = `/api/super-tabs/hosts/${this.machineId}/changes`
    // The rows it holds, by their etag: a Swarm whose rows still match comes back with none, so an active Swarm no longer
    // costs its whole rows every second (the Lead's ruling on #1726). A host that holds nothing asks as before.
    const held = Object.fromEntries([...this.tabs].flatMap(([tabId, tab]) => typeof tab.etag === 'string' ? [[tabId, tab.etag]] : []))
    const answer = readable<HostChanges>(Object.keys(held).length
      ? await this.backend(this.core, 'POST', form, (askFull ? { full: true, held } : { cursor: this.cursor!, held }) satisfies HostChangesRequest)
      : await this.backend(this.core, 'GET', `${form}?${askFull ? 'full=1' : `cursor=${this.cursor}`}`))
    // The answer says what it is: the server answers a bad or too old cursor in full, with no removed Swarms (review round 1).
    const full = answer.full === true
    const tabs = full ? new Map<string, HostTabRows>() : new Map(this.tabs)
    for (const tabId of answer.removedTabIds ?? []) tabs.delete(tabId)
    for (const tab of answer.tabs) {
      if (!('unchanged' in tab)) { tabs.set(tab.tabId, tab); continue }
      // Unchanged keeps the rows held. One it does not hold (it never named it) is dropped, and comes back whole next time.
      const kept = this.tabs.get(tab.tabId)
      if (kept) tabs.set(tab.tabId, { ...kept, etag: tab.etag, lastChangedAt: tab.lastChangedAt })
      else tabs.delete(tab.tabId)
    }
    this.tabs = tabs
    this.cursor = answer.cursor
    if (full) this.fullAt = startedAt
    this.readAt = this.now()
    const read = this.snapshot()
    for (const watcher of this.watchers) {
      try { watcher(read) } catch { /* A watcher's failure is its own. */ }
    }
    return read
  }

  /** Every Swarm's rows in one list each; a Swarm whose lists are not lists gives none, and never stops the others'. */
  private snapshot(): HostRead {
    const tabs = [...this.tabs.values()]
    const rows = (value: unknown) => Array.isArray(value) ? value.map(object) : []
    const isRecord = (value: unknown): value is Json => !!value && typeof value === 'object' && !Array.isArray(value)
    return { roster: tabs.flatMap(tab => rows(tab.roster)), pools: tabs.flatMap(tab => isRecord(tab.pool) ? [tab.pool] : []),
      assignments: tabs.flatMap(tab => rows(tab.assignments)) }
  }
}