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.

10.6 KB
Raw Blame
/**
 * A project's Product Manager switched to another engine from its own pane, as any pane is (Change agent; Dee, 11-01: "PM is
 * just an agent/pane like in v1"). Its stop is the one exception to "a Lead is never closed" (retention.ts mayBeLead), and a
 * narrow one (Lead, 11-01; security reviews 1 and 2 of #2493):
 * - Only a `now` close that names the switch's change id is considered, and only when this machine's own handoff receipt
 *   shows that very switch of that very agent was prepared moments ago. `agent_handoff_prepare` answers the machine's owner
 *   alone: the owner's apps, or any process on the owner's Mac, agents with a shell included, which could already stop the
 *   Product Manager's process or type into its terminal.
 * - That close gets a one-time pass, held in this process, which only the stop it starts carries (lib/closeAgentService.ts
 *   hands it to lib/stopAgentService.ts options). No other stop carries it, whoever asks: Stop Harness (a paired dial's
 *   included), a delete, a purge, a script's close. The stop uses it up; the close's end clears it, stopped or not; the same
 *   switch is never let through twice. A restart forgets it, which only refuses.
 * - The switch is recorded only once its stop went through, one per Product Manager. While it runs, a second switch is refused,
 *   and the host does not reopen the stopped one (superTabs/host.ts keepAlive), so the new session can take its place: the
 *   existing replacement report and the backend's agent.rebind keep the same Swarm agent, its lead and its work.
 * - The new session not started within SWITCH_HOLD_MS, the hold ends and the host reopens the old one on its old engine. A new
 *   session that runs but is not taken into the Swarm by SWITCH_ADOPT_MS, or starts after the old one was reopened, is closed
 *   by the host first, so no unlinked session runs beside the Product Manager. A project never has two, and never none for long.
 * The record is a file, so a restart in the middle keeps the hold and its limits.
 */
import { createHash, randomUUID } from 'node:crypto'
import { existsSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { handoffHash } from '../lib/handoffAuthority.js'
import { readPrivateStateFile, secureStateDirectory, syncStateDirectory } from '../lib/secureState.js'
import { mayBeBuddy, mayBeLead as retainedLead } from './retention.js'
import { identifier, object } from './wire.js'

/** How soon after its owner prepared the switch its close must come (Desktop closes at once after preparing). */
export const SWITCH_ARM_MS = 2 * 60_000
/** How long, from its stop, the host waits for the new session before it reopens the old one. */
export const SWITCH_HOLD_MS = 3 * 60_000
/** How long, from its stop, the host waits for the Swarm to take in a new session that runs (agent.rebind, every 5 s). */
export const SWITCH_ADOPT_MS = 10 * 60_000
/** Keep failed Buddy switches recoverable, and fence late starts, for this bounded window. */
export const SWITCH_RECOVERY_MS = 30 * 60_000
/** Ended records go after a day; each Product Manager has at most one. */
const KEEP_MS = 24 * 60 * 60_000
const CHANGE_ID = /^[0-9a-f]{32}$/
const MAX_RECEIPT_BYTES = 20 * 1024 * 1024
/** The switches this process let through, so none is let through twice; the oldest are forgotten past this many. */
const MAX_USED = 256

export interface LeadSwitch { version: 1; agentId: string; changeId: string; targetEngine: string; at: number; recovered?: true }

const folder = (dataDir: string) => join(dataDir, 'super-tabs', 'lead-switch')
const fileOf = (dataDir: string, agentId: string) => join(folder(dataDir), `${createHash('sha256').update(agentId).digest('hex')}.json`)

/** The pass a switch's close holds for the one stop it starts, by Product Manager: its change id. */
const passes = new Map<string, string>()
/** Every switch this process let through (`agentId:changeId`), with its engine: none is let through twice, and only these
 *  record. The oldest are forgotten past MAX_USED. */
const issued = new Map<string, string>()
/** The issued switches whose close ended. */
const ended = new Set<string>()

/** The switch recorded for [agentId], whether running or ended; null when none or unreadable. */
export function leadSwitchOf(dataDir: string, agentId: string): LeadSwitch | null {
  const file = fileOf(dataDir, agentId)
  if (!existsSync(file)) return null
  try {
    const row = object(JSON.parse(readPrivateStateFile(file, 4_096)))
    if (row.version !== 1 || row.agentId !== agentId || typeof row.changeId !== 'string' || !CHANGE_ID.test(row.changeId)
      || (row.recovered !== undefined && row.recovered !== true) || !identifier(row.targetEngine) || typeof row.at !== 'number' || !Number.isFinite(row.at)) return null
    return row as unknown as LeadSwitch
  } catch { return null }
}

/** Running: recorded [limit] ago or less, and not in the future (a clock set back holds no longer than this). */
export const switchWithin = (row: LeadSwitch | null, now: number, limit = SWITCH_HOLD_MS): row is LeadSwitch =>
  !!row && row.at <= now + 60_000 && now - row.at <= limit

/** The engine its owner prepared [agentId]'s switch [changeId] to, when this machine's handoff receipt shows it was done
 *  within SWITCH_ARM_MS; else null. The receipt is written only for the machine's owner (services/handoffRequest.ts). */
function prepared(dataDir: string, agentId: string, changeId: string, now: number): string | null {
  const file = join(dataDir, 'handoff-receipts', `${handoffHash(JSON.stringify([agentId, changeId]))}.json`)
  try {
    if (!existsSync(file)) return null
    const age = now - statSync(file).mtimeMs
    if (age > SWITCH_ARM_MS || age < -60_000) return null
    const receipt = object(JSON.parse(readPrivateStateFile(file, MAX_RECEIPT_BYTES)))
    const request = object(object(receipt.prepared).request)
    if (receipt.version !== 1 || receipt.committed !== true || request.agentId !== agentId || request.changeId !== changeId
      || !identifier(request.targetEngine)) return null
    return request.targetEngine as string
  } catch { return null }
}

function write(dataDir: string, row: LeadSwitch, now: number): void {
  const dir = folder(dataDir)
  secureStateDirectory(dir)
  for (const name of readdirSync(dir)) {
    if (!/^[a-f0-9]{64}\.json$/.test(name)) continue
    try { if (now - statSync(join(dir, name)).mtimeMs > KEEP_MS) unlinkSync(join(dir, name)) } catch { /* Gone already. */ }
  }
  const file = fileOf(dataDir, row.agentId), temporary = `${file}.${randomUUID()}.next`
  try {
    writeFileSync(temporary, JSON.stringify(row), { mode: 0o600, flush: true, flag: 'wx' })
    renameSync(temporary, file)
    syncStateDirectory(dir)
  } finally { if (existsSync(temporary)) unlinkSync(temporary) }
}

/** A successful Buddy rollback is durable: a later Stop Harness must never be mistaken for a failed launch. */
export function leadSwitchRecovered(dataDir: string, agentId: string, changeId: string): void {
  const row = leadSwitchOf(dataDir, agentId)
  if (!row || row.changeId !== changeId || row.recovered) return
  write(dataDir, { ...row, recovered: true }, Date.now())
}

/** Another switch of [agentId] than [changeId] is running, its close under way or its new session awaited: refused. */
export function leadSwitching(dataDir: string, agentId: string, changeId: string, now = Date.now()): boolean {
  const pass = passes.get(agentId)
  if (pass && pass !== changeId) return true
  const row = leadSwitchOf(dataDir, agentId)
  return switchWithin(row, now) && row.changeId !== changeId
}

/** Whether the close guard (lib/closeAgentService.ts) refuses a close of [agentId] naming [changeId] (a `now` close of Change
 *  agent) or none: refused for a Product Manager unless it is that switch's close, which then gets the pass for its one stop. */
export function leadCloseProtected(dataDir: string, agentId: string, changeId?: string, now = Date.now()): boolean {
  if (!retainedLead(dataDir, agentId)) return false
  return switchCloseProtected(dataDir, agentId, changeId, now)
}

/** A Buddy's close gets the same one-use handoff permit; Stop Harness keeps its ordinary behavior. */
export function buddyCloseProtected(dataDir: string, agentId: string, changeId?: string, now = Date.now()): boolean {
  if (!mayBeBuddy(dataDir, agentId, now)) return false
  return switchCloseProtected(dataDir, agentId, changeId, now)
}

function switchCloseProtected(dataDir: string, agentId: string, changeId: string | undefined, now: number): boolean {
  if (!changeId || !CHANGE_ID.test(changeId)) return true
  const key = `${agentId}:${changeId}`
  if (issued.has(key) || passes.has(agentId) || switchWithin(leadSwitchOf(dataDir, agentId), now)) return true
  const engine = prepared(dataDir, agentId, changeId, now)
  if (!engine) return true
  passes.set(agentId, changeId)
  issued.set(key, engine)
  if (issued.size > MAX_USED) issued.delete(issued.keys().next().value!)
  return false
}

/** The core's stop guard (core/agents/lifecycle.ts): a Product Manager is never stopped, but by the one stop of its switch's
 *  close, which carries the switch [leadSwitch] and uses its pass up. */
export function mayBeLead(dataDir: string, agentId: string, leadSwitch?: string): boolean {
  if (!retainedLead(dataDir, agentId)) return false
  if (!leadSwitch || passes.get(agentId) !== leadSwitch) return true
  passes.delete(agentId)
  return false
}

/** The switch's close ended (lib/closeAgentService.ts): its pass, used or not, is gone; stopped, the switch is recorded and the
 *  host's hold starts now. A close that failed records nothing, so its owner may switch again at once and a crashed Product
 *  Manager is reopened as ever. Only the close that was given the pass records: [changeId] must be one this process let
 *  through, and once. */
export function leadSwitchEnded(dataDir: string, agentId: string, changeId: string, stopped: boolean, now = Date.now()): void {
  if (passes.get(agentId) === changeId) passes.delete(agentId)
  const key = `${agentId}:${changeId}`, engine = issued.get(key)
  if (!stopped || engine === undefined || ended.has(key)) return
  ended.add(key)
  if (ended.size > MAX_USED) ended.delete(ended.values().next().value!)
  try { write(dataDir, { version: 1, agentId, changeId, targetEngine: engine, at: now }, now) } catch (error) {
    // Unrecorded, the host reopens the old one as for any stopped Product Manager: never none.
    console.warn(`[super-tabs] could not record the switch of ${agentId.slice(0, 8)}: ${error instanceof Error ? error.name : 'unknown'}`)
  }
}

/** Tests: forget this process's passes, as a restart does. */
export function resetLeadSwitchPassesForTest(): void { passes.clear(); issued.clear(); ended.clear() }