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.

12.2 KB
Raw Blame
/**
 * The daemon's half of the Harness GitHub App (docs/swarm-github-app.md): it asks the backend for the token of a local
 * Swarm agent's task, as that agent, and keeps the agent's gh login (lib/swarmGitHub.ts) holding a live token while the
 * task lasts and none after it.
 *
 * The token goes to git through `harness git-credential` (superTabs/gitCredential.ts), which asks here over the local
 * socket, and to gh through the session's own `hosts.yml`. Nothing here logs a token.
 */
import { readdirSync, readFileSync, rmSync, statSync, type Dirent } from 'node:fs'
import { join } from 'node:path'
import type { CoreApi } from '../core/api.js'
import { swarmGitHubRoot, swarmGitHubSessionDir, writeSessionGitHub } from '../lib/swarmGitHub.js'
import { backend, identifier, object, SuperTabHostError } from './wire.js'
import type { SwarmSources } from './host.js'
import type { HostRead } from './hostFeed.js'

type Json = Record<string, unknown>
type Session = NonNullable<ReturnType<CoreApi['agents']['byAgent']>>
const list = (value: unknown) => Array.isArray(value) ? value.map(object) : []
/** How old a host form a token request may take: git asks for one on every fetch and push, and the server checks the task on
 *  each request anyway. */
const ROSTER_FRESH_MS = 5_000

/** The session's own folder when it was started to use the app, else null. */
function githubDir(core: CoreApi, session: Session | undefined): string | null {
  const skill = session?.swarmSkill
  return skill?.github ? swarmGitHubSessionDir(core.dataDir, skill.key) : null
}

/** Refusals that mean the session must not keep a token: anything the backend decided, no app on the server, and an app
 *  GitHub refuses (backend github/app.ts `misconfigured`: GitHub answered 401 to the app's own credentials; security review
 *  of #2390). A backend that could not be reached, or GitHub not answering it (GITHUB_UNAVAILABLE), decides nothing, and an
 *  unexpired token stays. */
const DECIDED_5XX = new Set(['GITHUB_APP_NOT_CONFIGURED', 'GITHUB_APP_MISCONFIGURED'])
export const decided = (error: SuperTabHostError) => (error.status >= 400 && error.status < 500) || DECIDED_5XX.has(error.code)

/**
 * The token of [harnessId]'s task: asked as each Swarm membership this machine's roster lists for that harness (one,
 * nearly always), the first that has a task answering. For a session started to use the app, its gh login and commit
 * trailers are written from the answer, and its login emptied on a refusal.
 */
export async function githubToken(core: CoreApi, harnessId: string, sources: SwarmSources): Promise<Json> {
  const machineId = core.daemon.machineId()
  if (!identifier(machineId) || !identifier(harnessId)) return { error: 'INVALID_REQUEST' }
  const session = core.agents.byAgent(harnessId)
  if (!session) return { error: 'AGENT_UNAVAILABLE', detail: 'This harness is not running on this machine.' }
  const dir = githubDir(core, session)
  let refusal: Json | null = null
  try {
    const rows = list((await sources.feed.current(ROSTER_FRESH_MS)).roster).filter(row => {
      const agent = object(row.agent)
      return identifier(row.tabId) && identifier(agent.id) && agent.machineId === machineId && agent.harnessId === harnessId
        && row.closeSession !== true && row.stopRequested !== true
    })
    for (const row of rows) {
      const tabId = String(row.tabId), agentId = String(object(row.agent).id)
      try {
        const value = object(await backend(core, 'POST', `/api/super-tabs/${tabId}/github-token?asAgentId=${agentId}`, { machineId }))
        if (typeof value.token !== 'string' || typeof value.repository !== 'string') {
          throw new SuperTabHostError('GITHUB_UNAVAILABLE', 'The Harness server answered without a token.', 502)
        }
        if (dir) writeSessionGitHub(dir, value.token, Array.isArray(value.trailers) ? value.trailers.filter(t => typeof t === 'string') : [], value.commitAs ?? null)
        return { ok: true, value: { ...value, tabId, agentId } }
      } catch (error) {
        if (!(error instanceof SuperTabHostError)) throw error
        // A task in another Swarm this harness also belongs to is still worth asking for; any other refusal says more.
        if (!refusal || refusal.error === 'NO_ASSIGNMENT') refusal = { error: error.code, detail: error.message, status: error.status, decided: decided(error) }
      }
    }
  } catch (error) {
    if (!(error instanceof SuperTabHostError)) throw error
    refusal = { error: error.code, detail: error.message, status: error.status, decided: decided(error) }
  }
  refusal ??= { error: 'NOT_A_SWARM_AGENT', detail: 'This harness is not an agent in a Swarm on this machine.', decided: true }
  const { decided: final, ...answer } = refusal
  if (dir && final) writeSessionGitHub(dir, null)
  return answer
}

/** How often the daemon looks at its sessions' tasks. A token is renewed once it has this much left or less. */
export const REFRESH_INTERVAL_MS = 60_000
export const RENEW_BELOW_MS = 10 * 60_000
/** How long a session's folder with no session registered for it stays: longer than any start waits to launch, since a
 *  start writes the folder before its session is registered (core/agents/create.ts; review of #1998). */
export const UNREGISTERED_FOLDER_MS = 15 * 60_000

/**
 * Keeps each local session started to use the app holding a token for its task while the task lasts: renewed before it
 * runs out (the backend hands out a new one ten minutes before expiry), and taken away when the task ends, so gh, which
 * reads its login each time it runs, never holds a stale or finished task's token for long. One backend read a minute,
 * and only while such a session is running.
 */
export class GitHubTokenRefresher {
  private timer: NodeJS.Timeout | null = null
  private running: Promise<void> | null = null
  private readonly primed = new Map<string, { assignmentId: string; expiresAt: number }>()
  /** The assignment each session was last looked at for as soon as it arrived ([assigned]): one look per task, however
   *  often the host reads, even while its token cannot be had. */
  private readonly asked = new Map<string, string>()
  private readonly now: () => number
  private readonly intervalMs: number

  constructor(private readonly core: CoreApi, private readonly sources: () => SwarmSources, options: { now?: () => number; intervalMs?: number } = {}) {
    this.now = options.now ?? Date.now
    this.intervalMs = options.intervalMs ?? REFRESH_INTERVAL_MS
  }

  start(): void {
    if (this.timer) return
    this.timer = setInterval(() => { void this.tick() }, this.intervalMs)
    this.timer.unref?.()
    void this.tick()
  }

  stop(): void {
    if (this.timer) clearInterval(this.timer)
    this.timer = null
    this.primed.clear()
    this.asked.clear()
  }

  /**
   * The host read its Swarms' rows: a session started to use the app that has a task it holds no token for is looked at
   * now, not at the next minute's pass. Its gh login was empty for up to a minute after the task arrived, so a Builder's
   * first `gh auth status` said "You are not logged into any GitHub hosts" and it stopped (Mac Auto, 2026-10-29). Once per
   * task: a token that cannot be had is asked for again at the minute's pass, as before. Only while the refresher runs.
   */
  assigned(read: HostRead): void {
    if (!this.timer) return
    let due = false
    for (const session of this.core.agents.live()) {
      const id = session.agentId
      const task = read.assignments.find(row => row.harnessId === id && identifier(row.assignmentId))
      if (!task || this.primed.get(id)?.assignmentId === task.assignmentId || this.asked.get(id) === task.assignmentId) continue
      if (!githubDir(this.core, session)) continue
      this.asked.set(id, String(task.assignmentId))
      due = true
    }
    if (due) void this.tick()
  }

  /** One look; a look still running is not started twice. */
  tick(): Promise<void> {
    this.running ??= this.look().catch(error => {
      console.warn(`[super-tab] GitHub tokens not refreshed · ${error instanceof Error ? error.message : String(error)}`)
    }).finally(() => { this.running = null })
    return this.running
  }

  /**
   * A session that stopped takes its token with it: its folder's gh login is emptied. A task ended as its agent stopped left
   * the last token there, since only running sessions are looked at (local Team account run, 2026-10-28); so did a session
   * that stopped while no daemon ran. Looked at on every pass, not once: a token fetch still in flight as its session stopped
   * writes the token after the folder was emptied (security review of #1978). One small read per stopped session's folder a
   * minute, while the refresher runs. Anything that is not a session's folder is skipped, and one that cannot be read or
   * written is logged and passed over, so no folder stops the renewals below. A folder whose session is gone from this
   * machine is removed, so passes do not grow with every session ever run (security review of #1978); one whose session
   * stopped but may run again ([known]) keeps its commit identity and trailers for then. Removed only once untouched for
   * UNREGISTERED_FOLDER_MS: a session still starting has its folder before its record, and a record may not be read just
   * now (review of #1998).
   */
  private emptyStopped(running: ReadonlySet<string>, known: ReadonlySet<string>): void {
    const sessions = join(swarmGitHubRoot(this.core.dataDir), 'sessions')
    let entries: Dirent[]
    try { entries = readdirSync(sessions, { withFileTypes: true }) } catch { return }
    for (const entry of entries) {
      if (!entry.isDirectory()) continue
      const dir = swarmGitHubSessionDir(this.core.dataDir, entry.name)
      if (!dir || running.has(dir)) continue
      try {
        if (!known.has(dir) && this.now() - this.touched(dir) >= UNREGISTERED_FOLDER_MS) { rmSync(dir, { recursive: true, force: true }); continue }
        let hosts: string
        try { hosts = readFileSync(join(dir, 'gh', 'hosts.yml'), 'utf8') } catch { continue }
        if (hosts !== '{}\n') writeSessionGitHub(dir, null)
      } catch (error) {
        console.warn(`[super-tab] could not empty a stopped session's gh login · ${error instanceof Error ? error.message : String(error)}`)
      }
    }
  }

  /** When anything in a session's folder last changed. */
  private touched(dir: string): number {
    let newest = 0
    for (const path of [dir, join(dir, 'gh'), join(dir, 'gh', 'hosts.yml'), join(dir, 'gh', 'config.yml'), join(dir, 'gitconfig'), join(dir, 'trailers')]) {
      try { newest = Math.max(newest, statSync(path).mtimeMs) } catch { /* not there */ }
    }
    return newest
  }

  private async look(): Promise<void> {
    const sessions = this.core.agents.live().flatMap(session => {
      const dir = githubDir(this.core, session)
      return dir ? [{ session, dir }] : []
    })
    for (const id of this.primed.keys()) if (!sessions.some(s => s.session.agentId === id)) this.primed.delete(id)
    this.emptyStopped(new Set(sessions.map(s => s.dir)),
      new Set(this.core.agents.all().flatMap(session => githubDir(this.core, session) ?? [])))
    if (!sessions.length) return
    const machineId = this.core.daemon.machineId()
    if (!identifier(machineId)) return
    let work: Json[]
    // A fresh read each minute: a task that ended takes its token away within that minute.
    try { work = list((await this.sources().feed.refresh()).assignments) } catch (error) {
      if (error instanceof SuperTabHostError) return
      throw error
    }
    for (const { session, dir } of sessions) {
      const id = session.agentId
      const task = work.find(row => row.harnessId === id && identifier(row.assignmentId))
      if (!task) {
        // No task in its hands: no token in its gh login.
        writeSessionGitHub(dir, null)
        this.primed.delete(id)
        continue
      }
      const known = this.primed.get(id)
      if (known && known.assignmentId === task.assignmentId && known.expiresAt - this.now() > RENEW_BELOW_MS) continue
      const answer = await githubToken(this.core, id, this.sources())
      const expiresAt = Date.parse(String(object(answer.value).expiresAt))
      if (answer.ok === true && Number.isFinite(expiresAt)) this.primed.set(id, { assignmentId: String(task.assignmentId), expiresAt })
      else this.primed.delete(id)
    }
  }
}