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.4 KB
Raw Blame
export type OneShotEngine = 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'commandcode' | 'kilo'

const ONE_SHOT_ENGINES: readonly OneShotEngine[] = ['claude', 'codex', 'cursor', 'opencode', 'pi', 'commandcode', 'kilo']

export interface DisposableWorker<Options, Result> {
  readonly engine: OneShotEngine
  readonly createdAt: number
  isAlive(): boolean
  run(options: Options): Promise<Result>
  dispose(): void
  onExit(listener: () => void): void
}

export type ActiveEngineCounts = Record<OneShotEngine, number>

export function poolTargetForActiveSessions(active: number): number {
  if (!Number.isFinite(active) || active <= 0) return 0
  return Math.max(1, Math.ceil(active / 3))
}

interface EngineState<Options, Result> {
  active: number
  target: number
  starting: number
  ready: Set<DisposableWorker<Options, Result>>
  retryTimer: NodeJS.Timeout | null
  /** Consecutive warm-spawn failures. Drives the backoff and silences the log. */
  failures: number
}

/**
 * Warm-spawn retry backoff.
 *
 * A flat one-second retry is fine for a worker that crashed and will come back.
 * It is a disaster for a condition that never changes on its own — a missing or
 * unresolvable binary — because nothing in the loop ever notices it is losing.
 * MEASURED before this existed: one engine whose CLI could not be spawned
 * produced 69,341 log lines in ten hours, one process fork per second, forever.
 */
const RETRY_BASE_MS = 1_000
const RETRY_CAP_MS = 60_000
/** The attempt whose delay first reaches the cap — the last one that logs. */
const CAP_ANNOUNCE_AT = 7

export interface PoolSnapshot {
  enabled: boolean
  connected: boolean
  claude: { active: number; target: number; starting: number; ready: number }
  codex: { active: number; target: number; starting: number; ready: number }
  cursor: { active: number; target: number; starting: number; ready: number }
  opencode: { active: number; target: number; starting: number; ready: number }
  pi: { active: number; target: number; starting: number; ready: number }
  commandcode: { active: number; target: number; starting: number; ready: number }
  kilo: { active: number; target: number; starting: number; ready: number }
}

/** Maintains disposable, pre-spawned workers. A checked-out worker is never returned to the pool. */
export class DisposableOneShotPool<Options, Result> {
  private readonly states: Record<OneShotEngine, EngineState<Options, Result>> = {
    claude: { active: 0, target: 0, starting: 0, ready: new Set(), retryTimer: null, failures: 0 },
    codex: { active: 0, target: 0, starting: 0, ready: new Set(), retryTimer: null, failures: 0 },
    cursor: { active: 0, target: 0, starting: 0, ready: new Set(), retryTimer: null, failures: 0 },
    opencode: { active: 0, target: 0, starting: 0, ready: new Set(), retryTimer: null, failures: 0 },
    pi: { active: 0, target: 0, starting: 0, ready: new Set(), retryTimer: null, failures: 0 },
    commandcode: { active: 0, target: 0, starting: 0, ready: new Set(), retryTimer: null, failures: 0 },
    kilo: { active: 0, target: 0, starting: 0, ready: new Set(), retryTimer: null, failures: 0 },
  }
  private readonly all = new Set<DisposableWorker<Options, Result>>()
  private connected = false
  private enabled = false
  private closed = false
  private generation = 0
  private unwarmTimer: NodeJS.Timeout | null = null
  private sweepTimer: NodeJS.Timeout | null = null

  constructor(
    private readonly factory: (engine: OneShotEngine) => Promise<DisposableWorker<Options, Result>>,
    private readonly graceMs = 5 * 60_000,
    private readonly log: (line: string) => void = (line) => console.log(line),
    /** How long a warm worker may sit unused before it is replaced. A pooled worker is a real
     *  process parked on its stdin: with no ceiling it survives for as long as the adapter does.
     *  One was observed being handed out after 84 minutes, and another idling for 94 — a leak, and
     *  a stale model session for whoever eventually got it. `run()`'s timeout cannot help here; it
     *  only arms once a worker is assigned work. */
    private readonly maxIdleMs = 10 * 60_000,
  ) {}

  setActiveCounts(counts: ActiveEngineCounts): void {
    for (const engine of ONE_SHOT_ENGINES) {
      this.states[engine].active = Math.max(0, Math.floor(counts[engine] || 0))
    }
    this.reconcileAll()
  }

  setDeviceConnected(connected: boolean): void {
    if (this.closed) return
    this.connected = connected
    if (this.unwarmTimer) {
      clearTimeout(this.unwarmTimer)
      this.unwarmTimer = null
    }
    if (connected) {
      this.enabled = true
      this.startSweep()
      this.reconcileAll()
      return
    }
    if (!this.enabled) return
    this.unwarmTimer = setTimeout(() => {
      this.unwarmTimer = null
      if (this.connected || this.closed) return
      this.enabled = false
      this.reconcileAll()
      this.log('[one-shot-pool] device grace expired · unwarmed')
    }, this.graceMs)
  }

  async run(engine: OneShotEngine, options: Options): Promise<Result> {
    const state = this.states[engine]
    let worker: DisposableWorker<Options, Result> | undefined
    for (const candidate of state.ready) {
      state.ready.delete(candidate)
      if (candidate.isAlive() && !this.expired(candidate)) { worker = candidate; break }
      if (candidate.isAlive()) this.log(`[one-shot-pool] ${engine} dropped a stale warm worker · age=${Date.now() - candidate.createdAt}ms`)
      candidate.dispose()
      this.all.delete(candidate)
    }

    const hit = !!worker
    // The direct worker used by a miss is busy, not pool capacity. Refill the ready target now so a
    // concurrent recap can still hit a warm worker instead of waiting for this one to finish.
    this.reconcile(engine)
    const selected = worker ?? await this.createWorker(engine)

    const age = Date.now() - selected.createdAt
    this.log(`[one-shot-pool] ${engine} ${hit ? 'hit' : 'miss'} · workerAge=${age}ms · ready=${state.ready.size}/${state.target}`)
    try {
      return await selected.run(options)
    } finally {
      selected.dispose()
      this.all.delete(selected)
      this.reconcile(engine)
    }
  }

  /** Drop idle workers after a runtime config/model change; in-flight work remains isolated. */
  recycleReady(): void {
    this.generation++
    for (const engine of ONE_SHOT_ENGINES) {
      const state = this.states[engine]
      for (const worker of state.ready) worker.dispose()
      state.ready.clear()
    }
    this.reconcileAll()
  }

  shutdown(): void {
    if (this.closed) return
    this.closed = true
    this.enabled = false
    if (this.unwarmTimer) clearTimeout(this.unwarmTimer)
    this.unwarmTimer = null
    if (this.sweepTimer) clearInterval(this.sweepTimer)
    this.sweepTimer = null
    for (const worker of this.all) worker.dispose()
    this.all.clear()
    for (const engine of ONE_SHOT_ENGINES) {
      if (this.states[engine].retryTimer) clearTimeout(this.states[engine].retryTimer)
      this.states[engine].retryTimer = null
      this.states[engine].ready.clear()
      this.states[engine].target = 0
    }
  }

  snapshot(): PoolSnapshot {
    const item = (engine: OneShotEngine) => {
      const s = this.states[engine]
      return { active: s.active, target: s.target, starting: s.starting, ready: s.ready.size }
    }
    return {
      enabled: this.enabled,
      connected: this.connected,
      claude: item('claude'),
      codex: item('codex'),
      cursor: item('cursor'),
      opencode: item('opencode'),
      pi: item('pi'),
      commandcode: item('commandcode'),
      kilo: item('kilo'),
    }
  }

  private expired(worker: DisposableWorker<Options, Result>): boolean {
    return this.maxIdleMs > 0 && Date.now() - worker.createdAt >= this.maxIdleMs
  }

  /** Retire warm workers that have aged out. Runs on its own timer, because a pool nobody asks for
   *  a recap from is exactly the case where they would otherwise sit forever. */
  private sweepExpired(): void {
    for (const engine of ONE_SHOT_ENGINES) {
      const state = this.states[engine]
      for (const worker of [...state.ready]) {
        if (!this.expired(worker)) continue
        state.ready.delete(worker)
        worker.dispose()
        this.all.delete(worker)
        this.log(`[one-shot-pool] ${engine} retired an idle warm worker · age=${Date.now() - worker.createdAt}ms`)
      }
    }
    this.reconcileAll()
  }

  private startSweep(): void {
    if (this.sweepTimer || this.closed || this.maxIdleMs <= 0) return
    this.sweepTimer = setInterval(() => this.sweepExpired(), Math.max(1_000, Math.floor(this.maxIdleMs / 4)))
    // Never a reason to hold the process open for this.
    this.sweepTimer.unref?.()
  }

  private reconcileAll(): void {
    for (const engine of ONE_SHOT_ENGINES) this.reconcile(engine)
  }

  private reconcile(engine: OneShotEngine): void {
    if (this.closed) return
    const state = this.states[engine]
    const previousTarget = state.target
    state.target = this.enabled ? poolTargetForActiveSessions(state.active) : 0
    if (state.target !== previousTarget) {
      this.log(`[one-shot-pool] ${engine} target ${previousTarget}→${state.target} · active=${state.active}`)
    }

    if (state.target === 0 && state.retryTimer) {
      clearTimeout(state.retryTimer)
      state.retryTimer = null
    }
    // Going idle ends the streak. The next session of this engine deserves a
    // fast first attempt — the thing that was broken may well have been fixed
    // in between, and it is the only moment we get to find out cheaply.
    if (state.target === 0) state.failures = 0

    while (state.ready.size > state.target) {
      const worker = state.ready.values().next().value as DisposableWorker<Options, Result> | undefined
      if (!worker) break
      state.ready.delete(worker)
      worker.dispose()
      this.all.delete(worker)
    }
    while (!state.retryTimer && state.ready.size + state.starting < state.target) this.spawnPooled(engine)
  }

  private spawnPooled(engine: OneShotEngine): void {
    const state = this.states[engine]
    const generation = this.generation
    state.starting++
    void this.createWorker(engine)
      .then((worker) => {
        state.starting--
        if (generation !== this.generation || this.closed || !this.enabled || state.ready.size >= state.target || !worker.isAlive()) {
          worker.dispose()
          this.all.delete(worker)
          if (!this.closed && this.enabled && state.ready.size < state.target) this.scheduleRetry(engine)
        } else {
          state.ready.add(worker)
          state.failures = 0
          this.log(`[one-shot-pool] ${engine} warm ready=${state.ready.size}/${state.target}`)
          this.reconcile(engine)
        }
      })
      .catch((err) => {
        state.starting--
        state.failures++
        const delay = this.retryDelay(state)
        // Every attempt while the backoff is still growing, then ONCE at the
        // ceiling. A failure that cannot fix itself should say so and go quiet,
        // not narrate the same sentence every second until the log is 9MB.
        if (delay < RETRY_CAP_MS || state.failures === CAP_ANNOUNCE_AT) {
          this.log(
            `[one-shot-pool] ${engine} warm spawn failed (${state.failures}): ${err instanceof Error ? err.message : String(err)}`
            + (delay >= RETRY_CAP_MS ? ` · backing off to ${RETRY_CAP_MS / 1000}s and staying quiet` : ` · retry in ${delay}ms`),
          )
        }
        this.scheduleRetry(engine)
      })
  }

  private async createWorker(engine: OneShotEngine): Promise<DisposableWorker<Options, Result>> {
    const worker = await this.factory(engine)
    this.all.add(worker)
    worker.onExit(() => {
      this.all.delete(worker)
      const wasReady = this.states[engine].ready.delete(worker)
      if (wasReady) this.scheduleRetry(engine)
    })
    if (this.closed) {
      worker.dispose()
      this.all.delete(worker)
      throw new Error('one-shot pool shut down while worker was starting')
    }
    return worker
  }

  private scheduleRetry(engine: OneShotEngine): void {
    const state = this.states[engine]
    if (this.closed || !this.enabled || state.target === 0 || state.retryTimer) return
    state.retryTimer = setTimeout(() => {
      state.retryTimer = null
      this.reconcile(engine)
    }, this.retryDelay(state))
  }

  /** 1s, 2s, 4s … capped at a minute. Doubling is what makes a permanent failure cost nothing. */
  private retryDelay(state: EngineState<Options, Result>): number {
    const shift = Math.min(Math.max(state.failures - 1, 0), 6)
    return Math.min(RETRY_BASE_MS * 2 ** shift, RETRY_CAP_MS)
  }
}