@tonoid/agent-loop 1.0.0

package/src/lock.ts

@@ -0,0 +1,63 @@
+import { openSync, closeSync } from "node:fs"
+
+export interface LockImpl {
+  // Resolves once the lock is held; the returned function releases it.
+  acquire(path: string): Promise<() => void>
+}
+
+export function lockPath(repo: string): string {
+  return `${repo}/.git/agent-loop.lock`
+}
+
+export async function withRepoLock<T>(
+  repo: string,
+  impl: LockImpl,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const release = await impl.acquire(lockPath(repo))
+  try {
+    return await fn()
+  } finally {
+    release()
+  }
+}
+
+// In-process serialization, for tests and for a single tick's own passes.
+export function memoryLock(): LockImpl {
+  const chains = new Map<string, Promise<void>>()
+  return {
+    async acquire(path) {
+      let release!: () => void
+      const next = new Promise<void>((resolve) => { release = resolve })
+      const previous = chains.get(path) ?? Promise.resolve()
+      chains.set(path, previous.then(() => next))
+      await previous
+      return release
+    },
+  }
+}
+
+// An advisory whole-file lock through libc. Advisory and released by the
+// kernel on process death, including SIGKILL, so no lock file is ever deleted
+// by this program: an O_EXCL pidfile would deadlock permanently after a hard
+// kill, and mtime staleness heuristics are worse.
+export function fileLock(): LockImpl {
+  // Known ceiling: flock here is synchronous with no LOCK_NB, so a contested
+  // lock blocks the event loop. Upgrade path if that ever matters: LOCK_NB
+  // plus a bounded poll.
+  const LOCK_EX = 2
+  return {
+    async acquire(path) {
+      const { dlopen, FFIType } = await import("bun:ffi")
+      const { symbols } = dlopen("libc.so.6", {
+        flock: { args: [FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+      })
+      const fd = openSync(path, "a")
+      if (symbols.flock(fd, LOCK_EX) !== 0) {
+        closeSync(fd)
+        throw new Error(`could not lock ${path}`)
+      }
+      return () => closeSync(fd) // closing the descriptor releases the lock
+    },
+  }
+}

package/src/paths.ts

@@ -0,0 +1,21 @@
+import { homedir } from "node:os"
+import { isAbsolute, resolve } from "node:path"
+
+// Config paths are written with "~" because a human edits them.
+export function expandHome(p: string): string {
+  return p === "~" || p.startsWith("~/") ? `${homedir()}${p.slice(1)}` : p
+}
+
+// A versioned project folder names its paths relative to itself, so the folder
+// works on any box. Absolute and "~" paths still resolve, for the machine file
+// and for the rare path that really is machine-specific.
+export function resolveFrom(base: string, p: string): string {
+  const expanded = expandHome(p)
+  return isAbsolute(expanded) ? expanded : resolve(base, expanded)
+}
+
+// Every database, marker, and journal lives here. Overridable so the suite
+// never reads or writes the operator's real state.
+export function agentLoopHome(): string {
+  return process.env.AGENT_LOOP_HOME ?? `${homedir()}/.agent-loop`
+}

package/src/render.ts

@@ -0,0 +1,42 @@
+import type { Decision } from "./types"
+import { IDLE_REASON } from "./engine/spawn"
+
+const WOULD = new Set(["nudge", "escalate", "restart", "fail"])
+
+// A live tick really did the thing, and this line is the only view the operator
+// has of the loop: "WOULD sweep" for a worktree that is already gone reads as a
+// dry run. Verbs stay uppercase either way, matching DONE and EXTERNAL.
+export function renderDecision(d: Decision, live = false): string {
+  const would = (verb: string) => (live ? verb.toUpperCase() : `WOULD ${verb}`)
+  switch (d.pass) {
+    case "gc":
+      return `GC ${d.removed} marks`
+    case "tick":
+      return `TICK ${d.workspace} ${d.ms}ms`
+    case "sweep":
+      return d.action === "clean"
+        ? `${would("sweep")} ${d.job} ${d.worktree} (${d.reason})`
+        : `HOLD ${d.job} ${d.worktree} (${d.reason})`
+    case "monitor":
+      if (d.action === "busy") return `BUSY ${d.job} ${d.key} (${d.reason})`
+      if (d.action === "hold") return `HOLD ${d.job} ${d.key} (${d.reason})`
+      if (d.action === "blocked") return `BLOCKED ${d.job} ${d.key} (${d.reason})`
+      return WOULD.has(d.action)
+        ? `${would(d.action)} ${d.job} ${d.key} (${d.reason})`
+        : `${d.action.toUpperCase()} ${d.job} ${d.key} (${d.reason})`
+    case "spawn":
+      if (d.action === "spawn") {
+        const on = d.account ? ` on ${d.account}` : ""
+        return `${would("spawn")} ${d.job} ${d.key}${on} (${d.reason})`
+      }
+      return d.reason === IDLE_REASON ? `IDLE ${d.job}` : `SKIP ${d.job} (${d.reason})`
+    case "error":
+      return d.where === "workspace"
+        ? `ERROR workspace ${d.workspace} (${d.reason})`
+        : `ERROR ${d.job} ${d.where} (${d.reason})`
+    case "audit":
+      return `OVERFILED ${d.job} ${d.key} ${d.filed - d.budget} over budget (filed ${d.filed}, perRound ${d.budget})`
+    case "warn":
+      return `WARN ${d.job} (${d.reason})`
+  }
+}

package/src/router/budget.ts

@@ -0,0 +1,81 @@
+import type { Window } from "../types"
+
+export interface BudgetIn {
+  windows: Window[]
+  now: Date
+  reserve: number
+  // Held back per weekday the human still has inside this window, on top of
+  // the flat reserve. Zero leaves the flat reserve as the whole mechanism.
+  reservePerWeekday?: number
+  // What an hour of a Saturday or Sunday is worth against an hour of a weekday.
+  weekendWeight?: number
+  usageMax: number
+  releaseBefore: number
+  maxConcurrent: number
+  // Percentage points per minute per worker for this window.
+  rateFor(w: Window): number
+}
+
+export interface BudgetOut {
+  concurrency: number
+  limiting: string
+  detail: string
+}
+
+// How much working time a human still has inside this window, in weekday
+// equivalents, integrated hour by hour from now rather than counted in whole
+// days. Two reasons it is hours: a day counter jumps twenty points at midnight
+// on a window that did not change, and it can only value a Saturday at a whole
+// weekday or at nothing. Weekend hours are worth weekendWeight of a weekday
+// hour, so a weekend keeps a small assignment instead of none.
+export function weekdayEquivalents(now: Date, until: Date, weekendWeight = 0): number {
+  if (until.getTime() <= now.getTime()) return 0
+  let total = 0
+  let cursor = now
+  // A window longer than a year is a misread payload, not a reason to spin.
+  for (let guard = 0; cursor < until && guard < 366 * 24; guard++) {
+    const midnight = new Date(cursor.getFullYear(), cursor.getMonth(), cursor.getDate() + 1)
+    const end = midnight < until ? midnight : until
+    const day = cursor.getDay()
+    const weight = day === 0 || day === 6 ? weekendWeight : 1
+    total += ((end.getTime() - cursor.getTime()) / 86400000) * weight
+    cursor = end
+  }
+  return total
+}
+
+export function concurrencyFor(i: BudgetIn): BudgetOut {
+  let best: BudgetOut | null = null
+
+  for (const w of i.windows) {
+    // Clamped at one minute: at the instant of reset the true divisor is zero,
+    // which would report infinite headroom on a window with none.
+    const minutesToReset = Math.max(1, (w.resetsAt.getTime() - i.now.getTime()) / 60000)
+    // Quota the developer can no longer spend is not worth holding, so the
+    // reserve is released once the window is about to roll. usageMax is never
+    // released: the reserve breaks, the hard ceiling does not, so a worker
+    // never starts into a window that will 429 mid-task.
+    // The flat reserve is a floor under the per-weekday one, not an alternative
+    // to it, so an account can hold a minimum and still widen it when the
+    // human has more of the window left to work through.
+    const perWeekday =
+      (i.reservePerWeekday ?? 0) * weekdayEquivalents(i.now, w.resetsAt, i.weekendWeight ?? 0)
+    const reserveNow =
+      minutesToReset <= i.releaseBefore ? 0 : Math.min(100, Math.max(i.reserve, perWeekday))
+    const ceiling = Math.min(i.usageMax, 100 - reserveNow)
+    const budgetRate = (ceiling - w.percent) / minutesToReset
+    const rate = i.rateFor(w)
+    const workers = rate > 0 ? budgetRate / rate : 0
+    const concurrency = Math.max(0, Math.min(i.maxConcurrent, Math.round(workers)))
+
+    if (!best || concurrency < best.concurrency) {
+      best = {
+        concurrency,
+        limiting: w.kind,
+        detail: `${w.percent.toFixed(1)}% of ${ceiling.toFixed(1)} with ${Math.round(minutesToReset)}m left`,
+      }
+    }
+  }
+
+  return best ?? { concurrency: 0, limiting: "none", detail: "no windows" }
+}

package/src/router/providers/claude.ts

@@ -0,0 +1,177 @@
+import type { AccountConfig, AccountUsage, UsageReader, Window } from "../../types"
+import { CLAUDE_WINDOW_MINUTES, checkWindows } from "../window"
+import { expandHome } from "../../paths"
+import { renameSync, writeFileSync, readFileSync, unlinkSync, statSync } from "node:fs"
+
+export const USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
+export const TOKEN_URL = "https://console.anthropic.com/v1/oauth/token"
+// The public OAuth client id the CLI itself uses. Overridable per account via
+// oauthClientId; verify it against a live refresh before trusting a fleet to it.
+export const DEFAULT_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+// Access tokens live 8 hours. Refresh inside the last 10 minutes so a tick never
+// starts a read against a token that expires mid-flight.
+export const REFRESH_MARGIN_MS = 10 * 60_000
+
+export interface Creds {
+  accessToken: string
+  refreshToken: string
+  expiresAt: number
+  refreshTokenExpiresAt?: number
+}
+
+export interface ClaudeDeps {
+  readCreds(configDir: string): Promise<Creds | null>
+  refresh(c: Creds, clientId: string, configDir: string): Promise<Creds>
+  getUsage(token: string): Promise<{ status: number; body: any }>
+}
+
+// Atomic: a torn credentials file locks the account out until a human logs in
+// interactively. Written beside the target so the rename cannot cross devices,
+// and merged into the existing document so unrelated keys survive.
+export function writeCreds(configDir: string, creds: Creds): void {
+  const path = `${expandHome(configDir)}/.credentials.json`
+  const doc = JSON.parse(readFileSync(path, "utf8"))
+  doc.claudeAiOauth = {
+    ...doc.claudeAiOauth,
+    accessToken: creds.accessToken,
+    refreshToken: creds.refreshToken,
+    expiresAt: creds.expiresAt,
+  }
+  // Unique per writer: two ticks can refresh the same account in the same
+  // minute (accounts are global config, shared across workspaces). A shared
+  // tmp name lets one process rename the other's still-empty file over
+  // .credentials.json - the exact torn-file lockout this function exists to
+  // prevent, and the rename makes it durable.
+  const tmp = `${path}.${process.pid}.tmp`
+  try {
+    writeFileSync(tmp, JSON.stringify(doc, null, 2), { mode: statSync(path).mode & 0o777 })
+    renameSync(tmp, path)
+  } catch (err) {
+    // A leftover temp file here still carries a live access token.
+    try { unlinkSync(tmp) } catch {}
+    throw err
+  }
+}
+
+const no = (reason: string, exhausted?: boolean): AccountUsage =>
+  exhausted ? { readable: false, reason, exhausted } : { readable: false, reason }
+
+function resetsAtOf(raw: unknown): Date | null {
+  if (raw === null || raw === undefined) return null
+  const d = typeof raw === "number" ? new Date(raw * 1000) : new Date(String(raw))
+  return Number.isNaN(d.getTime()) ? null : d
+}
+
+export function makeClaudeReader(d: ClaudeDeps): UsageReader {
+  return async (a: AccountConfig, now: Date): Promise<AccountUsage> => {
+    const clientId = a.oauthClientId ?? DEFAULT_CLIENT_ID
+    const stored = await d.readCreds(a.configDir)
+    if (!stored) return no(`no credentials in ${a.configDir}`)
+
+    let creds = stored
+    if (creds.expiresAt - now.getTime() <= REFRESH_MARGIN_MS) {
+      try {
+        creds = await d.refresh(creds, clientId, a.configDir)
+      } catch (err) {
+        // An account held in reserve for headroom is refreshed by nobody else,
+        // so it goes blind within a day and the ranking inverts against the
+        // router's own purpose. Report the reason rather than a bare failure.
+        return no(`refresh failed: ${err}`)
+      }
+    }
+
+    let res = await d.getUsage(creds.accessToken)
+    if (res.status === 401) {
+      try {
+        creds = await d.refresh(creds, clientId, a.configDir)
+      } catch (err) {
+        return no(`refresh after 401 failed: ${err}`)
+      }
+      res = await d.getUsage(creds.accessToken)
+      if (res.status === 401) return no("401 after refresh")
+    }
+    // Exhausted is strictly more information than unknown, and unlike every
+    // other unreadable state allowWhenUnreadable must not resurrect it.
+    if (res.status === 429) return no("429 from the usage endpoint", true)
+    if (res.status !== 200) return no(`usage endpoint ${res.status}`)
+
+    const windows: Window[] = []
+    for (const l of (res.body?.limits ?? []) as any[]) {
+      const resetsAt = resetsAtOf(l.resets_at)
+      if (!resetsAt) continue
+      const windowMinutes = CLAUDE_WINDOW_MINUTES[l.kind]
+      // Never let windowMinutes be undefined: it makes every arithmetic result
+      // NaN, every comparison false, and the account permanently ineligible
+      // while the log says STARVED forever.
+      if (windowMinutes === undefined) {
+        throw new Error(`unrecognized usage window kind "${l.kind}" for account "${a.id}"`)
+      }
+      const model = l.scope?.model
+      if (model && a.model && model !== a.model) continue
+      windows.push({
+        kind: String(l.kind),
+        group: String(l.group ?? l.kind),
+        percent: Number(l.percent),
+        resetsAt,
+        windowMinutes,
+        scope: l.scope,
+        observedAt: now,
+      })
+    }
+
+    if (windows.length === 0) return no("no usable limit windows in the payload")
+    const bad = checkWindows(windows, now)
+    return bad ? no(bad) : { readable: true, windows }
+  }
+}
+
+export function liveClaudeDeps(live = false): ClaudeDeps {
+  return {
+    async readCreds(configDir) {
+      const f = Bun.file(`${expandHome(configDir)}/.credentials.json`)
+      if (!(await f.exists())) return null
+      const o = (await f.json())?.claudeAiOauth
+      if (!o?.accessToken || !o?.refreshToken) return null
+      return {
+        accessToken: String(o.accessToken),
+        refreshToken: String(o.refreshToken),
+        expiresAt: Number(o.expiresAt ?? 0),
+        refreshTokenExpiresAt: o.refreshTokenExpiresAt ? Number(o.refreshTokenExpiresAt) : undefined,
+      }
+    },
+    async refresh(c, clientId, configDir) {
+      const r = await fetch(TOKEN_URL, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          grant_type: "refresh_token",
+          refresh_token: c.refreshToken,
+          client_id: clientId,
+        }),
+      })
+      if (!r.ok) throw new Error(`token endpoint ${r.status}`)
+      const j: any = await r.json()
+      const next = {
+        accessToken: String(j.access_token),
+        refreshToken: c.refreshToken,
+        expiresAt: Date.now() + Number(j.expires_in ?? 0) * 1000,
+        refreshTokenExpiresAt: c.refreshTokenExpiresAt,
+      }
+      // A dry run keeps the refreshed token in memory: refresh tokens are not
+      // rotated, so the stored one keeps working and the file stays the live
+      // agent's to own. A live run writes it back, because an account nobody
+      // refreshes goes blind within a day.
+      if (live) writeCreds(configDir, next)
+      return next
+    },
+    async getUsage(token) {
+      const r = await fetch(USAGE_URL, {
+        headers: {
+          authorization: `Bearer ${token}`,
+          "anthropic-beta": "oauth-2025-04-20",
+        },
+      })
+      return { status: r.status, body: r.status === 200 ? await r.json() : null }
+    },
+  }
+}

package/src/router/providers/codex.ts

@@ -0,0 +1,120 @@
+import { Database } from "bun:sqlite"
+import { readdirSync } from "node:fs"
+import type { AccountConfig, AccountUsage, UsageReader, Window } from "../../types"
+import { checkWindows } from "../window"
+import { expandHome } from "../../paths"
+
+// Far enough back to cross a quiet weekend, short enough that a cold cache
+// costs a handful of file reads rather than a directory walk.
+export const ROLLOUT_SCAN_LIMIT = 20
+
+export interface CodexDeps {
+  indexPath(configDir: string): string | null
+  recentRollouts(indexPath: string, limit: number): string[]
+  readLines(path: string): Promise<string[]>
+}
+
+const no = (reason: string): AccountUsage => ({ readable: false, reason })
+
+function windowsFrom(rl: any, observedAt: Date): Window[] {
+  const out: Window[] = []
+  for (const slot of [rl?.primary, rl?.secondary]) {
+    if (!slot || slot.window_minutes == null || slot.resets_at == null) continue
+    const minutes = Number(slot.window_minutes)
+    out.push({
+      // Keyed on the window's own length, never on the slot name: the
+      // primary/secondary mapping is not stable across accounts or versions,
+      // and a slot-keyed EWMA silently compares two different windows.
+      kind: `w${minutes}`,
+      group: String(rl.limit_id ?? "codex"),
+      percent: Number(slot.used_percent),
+      resetsAt: new Date(Number(slot.resets_at) * 1000), // epoch seconds
+      windowMinutes: minutes,
+      observedAt,
+    })
+  }
+  return out
+}
+
+function lastRateLimits(lines: string[]): { rl: any; observedAt: Date } | null {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]!
+    if (!line.includes("rate_limits")) continue
+    try {
+      const ev = JSON.parse(line)
+      const rl = ev?.payload?.rate_limits
+      if (!rl) continue
+      const observedAt = new Date(ev.timestamp)
+      if (Number.isNaN(observedAt.getTime())) continue
+      return { rl, observedAt }
+    } catch {
+      continue // a torn last line in a session still being written
+    }
+  }
+  return null
+}
+
+export function makeCodexReader(d: CodexDeps): UsageReader {
+  return async (a: AccountConfig, now: Date): Promise<AccountUsage> => {
+    const index = d.indexPath(a.configDir)
+    if (!index) return no(`no session index in ${a.configDir}`)
+
+    for (const path of d.recentRollouts(index, ROLLOUT_SCAN_LIMIT)) {
+      const hit = lastRateLimits(await d.readLines(path))
+      if (!hit) continue
+      const windows = windowsFrom(hit.rl, hit.observedAt)
+      if (windows.length === 0) continue
+      const bad = checkWindows(windows, now)
+      return bad ? no(bad) : { readable: true, windows }
+    }
+    return no(`no rate_limits event in the ${ROLLOUT_SCAN_LIMIT} newest sessions`)
+  }
+}
+
+export function liveCodexDeps(): CodexDeps {
+  return {
+    indexPath(configDir) {
+      const dir = expandHome(configDir)
+      // A configured account whose codex directory hasn't been created yet
+      // (never logged in, or a fresh box) is an unreadable account, not a
+      // crash: readdirSync throws ENOENT, and every other failure path in
+      // this file returns null so the caller can shape it as { readable:
+      // false, reason }.
+      let names: string[]
+      try {
+        names = readdirSync(dir)
+      } catch {
+        return null
+      }
+      let best: { n: number; path: string } | null = null
+      for (const name of names) {
+        const m = name.match(/^state_(\d+)\.sqlite$/)
+        if (!m) continue
+        const n = Number(m[1])
+        if (!best || n > best.n) best = { n, path: `${dir}/${name}` }
+      }
+      return best?.path ?? null
+    },
+    recentRollouts(indexPath, limit) {
+      const db = new Database(indexPath, { readonly: true })
+      try {
+        // updated_at_ms is a later column and is null on rows written by older
+        // versions, where updated_at holds seconds.
+        return db
+          .query<{ rollout_path: string }, [number]>(
+            `SELECT rollout_path FROM threads
+             ORDER BY COALESCE(updated_at_ms, updated_at * 1000) DESC LIMIT ?`,
+          )
+          .all(limit)
+          .map((r) => r.rollout_path)
+      } finally {
+        db.close()
+      }
+    },
+    async readLines(path) {
+      const f = Bun.file(path)
+      if (!(await f.exists())) return []
+      return (await f.text()).split("\n")
+    },
+  }
+}

package/src/router/providers/grok.ts

@@ -0,0 +1,10 @@
+import type { UsageReader } from "../../types"
+
+// No usage signal exists: the billing record carries a period boundary and
+// zeroed on-demand credits, and the session logs record spend, not remaining.
+// Unreadable, and deliberately not exhausted, so allowWhenUnreadable can opt
+// the account back in.
+export const grokReader: UsageReader = async () => ({
+  readable: false,
+  reason: "no usage signal exists for this provider",
+})

package/src/router/rate.ts

@@ -0,0 +1,62 @@
+import type { GlobalStore, UsageSample } from "../globalstate"
+import type { AccountConfig, Window } from "../types"
+
+// Under a minute the percent resolution of the payload dominates the delta.
+export const MIN_SAMPLE_MINUTES = 1
+
+export function sampleRate(
+  prev: UsageSample,
+  cur: UsageSample,
+  workers: number,
+): number | null {
+  const elapsed = (cur.at - prev.at) / 60000
+  if (workers < 1 || elapsed < MIN_SAMPLE_MINUTES) return null
+  const delta = cur.percent - prev.percent
+  // A flat interval means the workers were not spending; a drop means the
+  // window rolled between snapshots. Neither measures a worker.
+  if (delta <= 0) return null
+  return delta / elapsed / workers
+}
+
+// The seed is one number standing in for a quantity that differs per window
+// kind by two orders of magnitude, so it is read against the window it prices:
+// 0.35 points/min is a worker burning about one 5-hour window over five hours,
+// and the same worker paces a weekly window over a week. Taken literally on a
+// weekly window instead, it claims a worker spends thirty-three window-fulls,
+// so budgetRate/rate rounds to zero workers and every account starves forever.
+// A measured EWMA is already per kind and is used as-is.
+export const SEED_REFERENCE_MINUTES = 300
+
+export function rateOf(
+  store: GlobalStore,
+  provider: string,
+  kind: string,
+  seed: number,
+  windowMinutes?: number,
+): number {
+  const learned = store.rate(provider, kind)
+  if (learned !== null && learned !== undefined) return learned
+  return windowMinutes && windowMinutes > 0
+    ? seed * (SEED_REFERENCE_MINUTES / windowMinutes)
+    : seed
+}
+
+export function recordAndLearn(
+  store: GlobalStore,
+  a: AccountConfig,
+  windows: Window[],
+  workers: number,
+): void {
+  for (const w of windows) {
+    const prev = store.lastUsage(a.id, w.kind, w.observedAt.getTime())
+    store.recordUsage(a.id, w)
+    // A human sharing the account lands in the same delta and would teach the
+    // fleet that a worker costs several times what it does, and one poisoned
+    // sample starves every account: the EWMA is per provider, not per account.
+    // Only an account explicitly declared loop-only may teach it. A zero
+    // reserve does not imply that; it only says nothing is being held back.
+    if (!a.soleConsumer || !prev) continue
+    const s = sampleRate(prev, { percent: w.percent, at: w.observedAt.getTime() }, workers)
+    if (s !== null) store.observeRate(a.provider, w.kind, s)
+  }
+}