@capagents/forgeqe 0.0.0-stage → 1.0.0

package/src/update.ts

@@ -0,0 +1,311 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs"
+import path from "node:path"
+import { packageVersion } from "./tui/theme.ts"
+
+export const NPM_PACKAGE = "@capagents/forgeqe"
+export const PYPI_PACKAGE = "forgeqe-cli"
+const NPM_REGISTRY = "https://registry.npmjs.org"
+const PYPI = "https://pypi.org/pypi"
+
+export type InstallKind = "bun" | "npm" | "pip"
+
+export interface Install {
+  kind: InstallKind
+  /** The `forgeqe` found on PATH. */
+  bin: string
+  /** What it resolves to (the package's entry, or the pip script). */
+  target: string
+  version: string
+  /** The Python that owns a pip install. */
+  python?: string
+}
+
+export interface UpdateDeps {
+  fetch: typeof fetch
+  run: (cmd: string, args: string[]) => { status: number | null; stdout: string; stderr: string }
+  env: NodeJS.ProcessEnv
+  platform: NodeJS.Platform
+  sleep: (ms: number) => Promise<void>
+  now: () => number
+}
+
+export function defaultDeps(): UpdateDeps {
+  return {
+    fetch,
+    run: (cmd, args) => {
+      const r = spawnSync(cmd, args, { encoding: "utf8" })
+      return { status: r.error ? null : r.status, stdout: r.stdout || "", stderr: r.stderr || (r.error ? String(r.error.message) : "") }
+    },
+    env: process.env,
+    platform: process.platform,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: () => Date.now(),
+  }
+}
+
+/** Newest first; prerelease tags sort before their release. */
+export function compareVersions(a: string, b: string): number {
+  const parse = (v: string) => {
+    const [core, pre = ""] = v.replace(/^v/, "").split("-", 2)
+    return { parts: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre }
+  }
+  const x = parse(a)
+  const y = parse(b)
+  for (let i = 0; i < Math.max(x.parts.length, y.parts.length); i++) {
+    const d = (x.parts[i] || 0) - (y.parts[i] || 0)
+    if (d) return d
+  }
+  if (x.pre === y.pre) return 0
+  if (!x.pre) return 1
+  if (!y.pre) return -1
+  return x.pre < y.pre ? -1 : 1
+}
+
+const NO_CACHE = { "Cache-Control": "no-cache", Pragma: "no-cache" }
+
+/** The registry's `latest` tag, asked past the CDN's cached copy. */
+export async function latestVersion(deps: UpdateDeps): Promise<string> {
+  const res = await deps.fetch(`${NPM_REGISTRY}/${NPM_PACKAGE}?t=${deps.now()}`, { headers: { ...NO_CACHE, Accept: "application/json" } })
+  if (!res.ok) throw new Error(`npm registry answered ${res.status} for ${NPM_PACKAGE}`)
+  const body = (await res.json()) as { "dist-tags"?: { latest?: string } }
+  const latest = body["dist-tags"]?.latest
+  if (!latest) throw new Error(`npm registry has no latest version of ${NPM_PACKAGE}`)
+  return latest
+}
+
+/**
+ * Whether installers can fetch this version yet: the registry lists it and serves its tarball.
+ * Right after a publish the registry can answer with the old version list, or 404 the tarball, for several minutes.
+ */
+export async function npmReady(version: string, deps: UpdateDeps): Promise<boolean> {
+  try {
+    const meta = await deps.fetch(`${NPM_REGISTRY}/${NPM_PACKAGE}/${version}?t=${deps.now()}`, { headers: { ...NO_CACHE, Accept: "application/json" } })
+    if (!meta.ok) return false
+    const tarball = `${NPM_REGISTRY}/${NPM_PACKAGE}/-/${NPM_PACKAGE.split("/")[1]}-${version}.tgz?t=${deps.now()}`
+    const res = await deps.fetch(tarball, { method: "HEAD", headers: NO_CACHE })
+    return res.ok
+  } catch {
+    return false
+  }
+}
+
+export async function pypiReady(version: string, deps: UpdateDeps): Promise<boolean> {
+  try {
+    const res = await deps.fetch(`${PYPI}/${PYPI_PACKAGE}/${version}/json?t=${deps.now()}`, { headers: NO_CACHE })
+    return res.ok
+  } catch {
+    return false
+  }
+}
+
+/** Polls `ready` until it holds or `timeoutMs` passes; true when it held. */
+export async function waitUntil(
+  ready: () => Promise<boolean>,
+  deps: UpdateDeps,
+  opts: { timeoutMs: number; everyMs?: number; onWait?: (waitedMs: number) => void },
+): Promise<boolean> {
+  const start = deps.now()
+  const every = opts.everyMs ?? 15_000
+  for (;;) {
+    if (await ready()) return true
+    const waited = deps.now() - start
+    if (waited + every > opts.timeoutMs) return false
+    opts.onWait?.(waited)
+    await deps.sleep(every)
+  }
+}
+
+function isFile(p: string): boolean {
+  try {
+    return statSync(p).isFile()
+  } catch {
+    return false
+  }
+}
+
+function packageDirOf(file: string): string | undefined {
+  let dir = path.dirname(file)
+  for (let i = 0; i < 6; i++) {
+    const pkg = path.join(dir, "package.json")
+    if (existsSync(pkg)) {
+      try {
+        if (JSON.parse(readFileSync(pkg, "utf8")).name === NPM_PACKAGE) return dir
+      } catch {
+        // not ours
+      }
+    }
+    const up = path.dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+  return undefined
+}
+
+function pythonOfScript(script: string, platform: NodeJS.Platform): string | undefined {
+  if (platform === "win32") {
+    const dir = path.dirname(script)
+    if (path.basename(dir).toLowerCase() !== "scripts") return undefined
+    const python = path.join(path.dirname(dir), "python.exe")
+    return existsSync(python) ? python : undefined
+  }
+  let first = ""
+  try {
+    first = readFileSync(script, "utf8").split("\n", 1)[0]
+  } catch {
+    return undefined
+  }
+  const m = first.match(/^#!\s*(\S*python[\d.]*)\s*$/)
+  return m ? m[1] : undefined
+}
+
+/** Every `forgeqe` on PATH, in PATH order, and how each was installed. The first one is what the shell runs. */
+export function findInstalls(deps: UpdateDeps): Install[] {
+  const exe = deps.platform === "win32" ? ["forgeqe.exe", "forgeqe.cmd", "forgeqe"] : ["forgeqe"]
+  const sep = deps.platform === "win32" ? ";" : ":"
+  const seen = new Set<string>()
+  const installs: Install[] = []
+  for (const dir of (deps.env.PATH || "").split(sep).filter(Boolean)) {
+    for (const name of exe) {
+      const bin = path.join(dir, name)
+      if (!isFile(bin)) continue
+      let target = bin
+      if (/[\\/]\.pyenv[\\/]shims$/.test(dir)) {
+        const r = deps.run("pyenv", ["which", "forgeqe"])
+        if (r.status !== 0 || !r.stdout.trim()) continue
+        target = r.stdout.trim()
+      }
+      try {
+        target = realpathSync(target)
+      } catch {
+        continue
+      }
+      if (seen.has(target)) continue
+      seen.add(target)
+      const pkgDir = packageDirOf(target)
+      if (pkgDir) {
+        let version = ""
+        try {
+          version = String(JSON.parse(readFileSync(path.join(pkgDir, "package.json"), "utf8")).version || "")
+        } catch {
+          // leave it blank
+        }
+        const kind: InstallKind = /[\\/]\.bun[\\/]/.test(pkgDir) ? "bun" : "npm"
+        installs.push({ kind, bin, target, version })
+        continue
+      }
+      const python = pythonOfScript(target, deps.platform)
+      if (!python) continue
+      const r = deps.run(python, ["-c", "import forgeqe_cli; print(forgeqe_cli.__version__)"])
+      if (r.status !== 0) continue
+      installs.push({ kind: "pip", bin, target, version: r.stdout.trim(), python })
+    }
+  }
+  return installs
+}
+
+function bunCommand(env: NodeJS.ProcessEnv): string {
+  const self = path.basename(process.execPath).toLowerCase()
+  if (self.startsWith("bun")) return process.execPath
+  const home = env.HOME || env.USERPROFILE
+  const bundled = home ? path.join(home, ".bun", "bin", process.platform === "win32" ? "bun.exe" : "bun") : ""
+  return bundled && existsSync(bundled) ? bundled : "bun"
+}
+
+/** The commands that move one install to `version`; each skips the installer's cached copy of the version list. */
+export function updateCommands(install: Install, version: string, env: NodeJS.ProcessEnv): Array<[string, string[]]> {
+  switch (install.kind) {
+    case "bun": {
+      const bun = bunCommand(env)
+      return [
+        [bun, ["pm", "cache", "rm"]],
+        [bun, ["add", "-g", `${NPM_PACKAGE}@${version}`, "--no-cache"]],
+      ]
+    }
+    case "npm":
+      return [["npm", ["install", "-g", `${NPM_PACKAGE}@${version}`, "--prefer-online"]]]
+    case "pip":
+      return [[install.python || "python3", ["-m", "pip", "install", "--upgrade", "--no-cache-dir", `${PYPI_PACKAGE}==${version}`]]]
+  }
+}
+
+export function commandLine([cmd, args]: [string, string[]]): string {
+  return [cmd, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")
+}
+
+export interface UpdateOptions {
+  /** A version to install instead of the latest. */
+  version?: string
+  /** Only report what would change. */
+  check?: boolean
+  /** How long to wait for the registries to serve a new release, in minutes. */
+  waitMinutes?: number
+  log?: (text: string) => void
+}
+
+export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaultDeps()): Promise<number> {
+  const log = opts.log || ((text: string) => console.log(text))
+  const installs = findInstalls(deps)
+  if (!installs.length) {
+    log(`No forgeqe install found on PATH (running ${packageVersion()} from ${process.argv[1] || "a checkout"}).`)
+    log(`Install it with: bun add -g ${NPM_PACKAGE}`)
+    return 1
+  }
+  const target = opts.version || (await latestVersion(deps))
+  for (const [i, inst] of installs.entries()) {
+    const state = !inst.version ? "version unknown" : compareVersions(inst.version, target) >= 0 ? "up to date" : `→ ${target}`
+    log(`${i === 0 ? "runs " : "also "} ${inst.kind.padEnd(3)}  ${(inst.version || "?").padEnd(8)} ${state.padEnd(16)} ${inst.bin}`)
+  }
+  const stale = installs.filter((inst) => !inst.version || compareVersions(inst.version, target) < 0)
+  if (!stale.length) {
+    log(`\nforgeqe ${target} is the latest; nothing to update.`)
+    return 0
+  }
+  if (opts.check) {
+    log(`\nforgeqe update installs ${target}:`)
+    for (const inst of stale) for (const c of updateCommands(inst, target, deps.env)) log(`  ${commandLine(c)}`)
+    return 0
+  }
+
+  const timeoutMs = Math.max(0, opts.waitMinutes ?? 20) * 60_000
+  const onWait = (what: string) => (waited: number) =>
+    log(`  ${what} ${target} is published but not served yet (registries take a few minutes); waited ${Math.round(waited / 1000)}s`)
+  if (stale.some((inst) => inst.kind !== "pip")) {
+    if (!(await waitUntil(() => npmReady(target, deps), deps, { timeoutMs, onWait: onWait("npm") }))) {
+      log(`\nnpm does not serve ${NPM_PACKAGE}@${target} yet. Run forgeqe update again in a few minutes.`)
+      return 1
+    }
+  }
+  if (stale.some((inst) => inst.kind === "pip")) {
+    if (!(await waitUntil(() => pypiReady(target, deps), deps, { timeoutMs, onWait: onWait("PyPI") }))) {
+      log(`\nPyPI does not serve ${PYPI_PACKAGE}==${target} yet. Run forgeqe update again in a few minutes.`)
+      return 1
+    }
+  }
+
+  let failed = 0
+  for (const inst of stale) {
+    log(`\nUpdating the ${inst.kind} install (${inst.bin})`)
+    for (const c of updateCommands(inst, target, deps.env)) {
+      log(`  $ ${commandLine(c)}`)
+      const r = deps.run(c[0], c[1])
+      if (r.status !== 0) {
+        const cacheStep = c[1][0] === "pm" && c[1][1] === "cache"
+        if (cacheStep) continue
+        failed++
+        log((r.stderr || r.stdout).trim().split("\n").slice(-5).map((l) => `  ${l}`).join("\n"))
+        break
+      }
+    }
+  }
+  const after = findInstalls(deps)
+  log("")
+  for (const inst of after) log(`${inst.kind.padEnd(3)}  ${(inst.version || "?").padEnd(8)} ${inst.bin}`)
+  const behind = after.filter((inst) => !inst.version || compareVersions(inst.version, target) < 0)
+  if (failed || behind.length) {
+    log(`\n${behind.length || failed} install(s) are still behind ${target}; the output above says why.`)
+    return 1
+  }
+  log(`\nforgeqe ${target} is installed. Open a new terminal (or run hash -r) if the shell still finds the old one.`)
+  return 0
+}

package/src/usage.ts

@@ -0,0 +1,158 @@
+import type { Usage } from "./types.ts"
+import { formatTokens } from "./tui/theme.ts"
+
+/**
+ * Tokens and what they cost. `input` counts every prompt token, `cached` the part of it the provider served from its
+ * prompt cache (billed at `price.cachedInput` when the profile sets it). A meter records every model session's usage
+ * by role, so each request and job can say what it used and cost.
+ */
+
+export type Price = {
+  input: number
+  output: number
+  currency: string
+  cachedInput?: number
+  /** Anthropic-style prompt-cache writes, per million; without it they cost the input price. */
+  cacheWrite?: number
+  /** Where the price came from when not all of it is from llms.json (a list price, or a list's cache discount). */
+  note?: string
+  /** Part of the price is derived (a list's cache discount applied to a price from llms.json). */
+  estimate?: boolean
+}
+
+export type Cost = {
+  amount: number
+  currency: string
+  /** Cached input billed at the full input rate: no cached price is known, so the amount is an upper bound. */
+  cachedAtFullRate?: boolean
+  /** Where the price came from, when not from llms.json ("list price from models.dev, 2026-10-06"). */
+  note?: string
+  /** Part of the price is derived, so the amount is an estimate. */
+  estimate?: boolean
+}
+
+export const NO_USAGE: Usage = { input: 0, output: 0 }
+
+export function addUsage(a: Usage, b: Usage | undefined): Usage {
+  if (!b) return { ...a }
+  const cached = (a.cached || 0) + (b.cached || 0)
+  const cacheWrite = (a.cacheWrite || 0) + (b.cacheWrite || 0)
+  return { input: a.input + b.input, output: a.output + b.output, ...(cached ? { cached } : {}), ...(cacheWrite ? { cacheWrite } : {}) }
+}
+
+/** What `usage` costs at `price` (per million tokens); undefined without a price. */
+export function costOf(usage: Usage | undefined, price: Price | undefined): Cost | undefined {
+  if (!usage || !price) return undefined
+  const cached = Math.min(usage.cached || 0, usage.input)
+  const written = Math.min(usage.cacheWrite || 0, usage.input - cached)
+  const amount =
+    ((usage.input - cached - written) * price.input + cached * (price.cachedInput ?? price.input) + written * (price.cacheWrite ?? price.input) + usage.output * price.output) /
+    1_000_000
+  return {
+    amount,
+    currency: price.currency,
+    ...(cached && price.cachedInput === undefined ? { cachedAtFullRate: true } : {}),
+    ...(price.note ? { note: price.note } : {}),
+    ...(price.estimate && cached ? { estimate: true } : {}),
+  }
+}
+
+export function addCost(a: Cost | undefined, b: Cost | undefined): Cost | undefined {
+  if (!a) return b
+  if (!b) return a
+  if (a.currency !== b.currency) return a
+  const note = a.note || b.note
+  return {
+    amount: a.amount + b.amount,
+    currency: a.currency,
+    ...(a.cachedAtFullRate || b.cachedAtFullRate ? { cachedAtFullRate: true } : {}),
+    ...(note ? { note } : {}),
+    ...(a.estimate || b.estimate ? { estimate: true } : {}),
+  }
+}
+
+/** US$1.42, £0.07, $0.0031 for amounts under a cent. */
+export function formatCost(c: Cost): string {
+  const digits = c.amount > 0 && c.amount < 0.01 ? 4 : 2
+  try {
+    return new Intl.NumberFormat("en", { style: "currency", currency: c.currency, minimumFractionDigits: digits, maximumFractionDigits: digits }).format(c.amount)
+  } catch {
+    return `${c.amount.toFixed(digits)} ${c.currency}`
+  }
+}
+
+/** "1.2M tokens (1.1M in, 980K of it cached · 36K out) · US$1.42": what one job or request used and cost. */
+export function usageLine(usage: Usage, cost?: Cost | null): string {
+  const total = usage.input + usage.output
+  const cached = usage.cached ? `, ${formatTokens(usage.cached)} of it cached` : ""
+  const tokens = `${formatTokens(total)} tokens (${formatTokens(usage.input)} in${cached} · ${formatTokens(usage.output)} out)`
+  if (!cost) return `${tokens} · cost unknown: add a price to the profile in llms.json`
+  // Honest about what the amount is: exact, at list price, an estimate, or an upper bound.
+  if (cost.cachedAtFullRate) return `${tokens} · up to ${formatCost(cost)} (cached input at the full input rate: no cached price is known for this model; set price.cached_input in llms.json)`
+  if (cost.estimate) return `${tokens} · ≈${formatCost(cost)} (${cost.note || "estimated"}; set price.cached_input in llms.json to be exact)`
+  if (cost.note) return `${tokens} · ${formatCost(cost)} (${cost.note})`
+  return `${tokens} · ${formatCost(cost)}`
+}
+
+// ---------------------------------------------------------------------------------------------
+// The meter: every model session reports here, by role
+// ---------------------------------------------------------------------------------------------
+
+export type Role = "ForgeQE's agent" | "browser agent" | "Scribe" | "reviewer" | "judge"
+
+type Entry = { usage: Usage; cost?: Cost; priced: boolean }
+
+const meter = new Map<Role, Entry>()
+
+/** Add `usage` (a delta, not a running total) for `role`, priced at `price` when known. */
+export function recordUsage(role: Role, usage: Usage, price: Price | undefined): void {
+  if (!usage.input && !usage.output) return
+  const e = meter.get(role) || { usage: { ...NO_USAGE }, priced: true }
+  e.usage = addUsage(e.usage, usage)
+  const cost = costOf(usage, price)
+  e.cost = addCost(e.cost, cost)
+  e.priced = e.priced && Boolean(cost)
+  meter.set(role, e)
+}
+
+export type MeterSnapshot = Map<Role, Entry>
+
+export function meterSnapshot(): MeterSnapshot {
+  return new Map([...meter].map(([k, v]) => [k, { usage: { ...v.usage }, cost: v.cost && { ...v.cost }, priced: v.priced }]))
+}
+
+/** What each role used and cost since `before`, and the total. */
+export function meterSince(before: MeterSnapshot): { total: Usage; cost?: Cost; priced: boolean; roles: { role: Role; usage: Usage; cost?: Cost }[] } {
+  const roles: { role: Role; usage: Usage; cost?: Cost }[] = []
+  let total: Usage = { ...NO_USAGE }
+  let cost: Cost | undefined
+  let priced = true
+  for (const [role, now] of meter) {
+    const was = before.get(role)
+    const usage: Usage = {
+      input: now.usage.input - (was?.usage.input || 0),
+      output: now.usage.output - (was?.usage.output || 0),
+      ...(now.usage.cached || was?.usage.cached ? { cached: (now.usage.cached || 0) - (was?.usage.cached || 0) } : {}),
+    }
+    if (!usage.input && !usage.output) continue
+    const c = now.cost ? { ...now.cost, amount: now.cost.amount - (was?.cost?.amount || 0) } : undefined
+    roles.push({ role, usage, cost: c })
+    total = addUsage(total, usage)
+    cost = addCost(cost, c)
+    priced = priced && now.priced
+  }
+  return { total, cost: priced ? cost : undefined, priced, roles }
+}
+
+/** "This request used 1.2M tokens (…) · US$1.42 — ForgeQE's agent 40K · US$0.11, Scribe 1.1M · US$1.25, …" */
+export function requestLine(before: MeterSnapshot, label = "This request used"): string {
+  const m = meterSince(before)
+  if (!m.roles.length) return ""
+  const parts = m.roles.map((r) => `${r.role} ${formatTokens(r.usage.input + r.usage.output)}${r.cost ? ` · ${formatCost(r.cost)}` : ""}`)
+  return `${label} ${usageLine(m.total, m.cost)}${m.roles.length > 1 ? ` — ${parts.join(", ")}` : ""}`
+}
+
+/** Tests: forget everything recorded so far. */
+export function resetMeter(): void {
+  meter.clear()
+}