getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/providers/process.ts

@@ -0,0 +1,268 @@
+import { cliHomesEnv } from '../cli-homes.ts';
+import { execFileSync, spawn } from 'node:child_process';
+import { mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Readable } from 'node:stream';
+import { log } from '../log.ts';
+import { nowIso } from '../util.ts';
+import type { ProviderError } from './types.ts';
+
+/** All an agent CLI inherits from the server: no API keys, server settings, or another agent session's variables. */
+export const INHERITED_ENV = ['HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'TERM', 'TZ', 'TMPDIR', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'DISABLE_AUTOUPDATER', 'DISABLE_UPDATES'];
+const INHERITED = new Set(INHERITED_ENV);
+
+export function agentEnv(extra: Record<string, string>, from: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [k, v] of Object.entries(from)) {
+    if (v !== undefined && (INHERITED.has(k) || k.startsWith('LC_'))) env[k] = v;
+  }
+  return { ...env, ...extra, ...cliHomesEnv(from) };
+}
+
+/** Feed each JSON line of `stream` to `onEvent`, skipping other lines. Returns a function that feeds an unterminated last line. */
+export function jsonLines(stream: Readable, onEvent: (event: any) => void): () => void {
+  let buf = '';
+  const feed = (line: string) => {
+    if (!line) return;
+    try {
+      onEvent(JSON.parse(line));
+    } catch {}
+  };
+  stream.setEncoding('utf8');
+  stream.on('data', (chunk: string) => {
+    buf += chunk;
+    let nl: number;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      feed(line);
+    }
+  });
+  return () => feed(buf.trim());
+}
+
+interface JsonlRun {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  stderr: string;
+  /** Stopped by `signal` before the CLI said its turn was over or ran past its time. */
+  aborted: boolean;
+  /** Ran past `timeoutMs` before the CLI said its turn was over or a stop came. */
+  timedOut: boolean;
+}
+
+export function runJsonl(
+  cmd: string,
+  args: string[],
+  opts: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdin: string;
+    signal: AbortSignal;
+    timeoutMs: number;
+    onEvent: (event: any) => void;
+    /**
+     * The event that ends the CLI's turn as a success (its result): a stop or the time limit after it only stops a process
+     * that is exiting. A failure it writes and then hangs is still timed out or stopped.
+     */
+    isDone?: (event: any) => boolean;
+    groupDir?: string;
+  },
+): Promise<JsonlRun> {
+  return new Promise((resolve, reject) => {
+    // Its own process group, so a stop kills the commands it started too.
+    const child = spawn(cmd, args, { cwd: opts.cwd, env: opts.env, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+    let stderr = '';
+    let aborted = false;
+    let timedOut = false;
+    // The CLI said its turn succeeded: what comes after is only it exiting.
+    let ended = false;
+    const record = opts.groupDir && child.pid ? recordGroup(opts.groupDir, child.pid, cmd) : null;
+    const forget = () => {
+      if (record) unlinkQuietly(record);
+    };
+
+    const kill = () => {
+      try {
+        if (child.pid) process.kill(-child.pid, 'SIGTERM');
+      } catch {}
+      setTimeout(() => {
+        try {
+          if (child.pid) process.kill(-child.pid, 'SIGKILL');
+        } catch {}
+      }, 3000).unref();
+    };
+    // Whichever ends the turn first is why it ended: its result, a stop, or the time limit. A stop that comes while a
+    // timed-out process is exiting doesn't make it stopped, and a result it writes once killed doesn't make it succeed.
+    const onAbort = () => {
+      if (!timedOut && !ended) aborted = true;
+      kill();
+    };
+    opts.signal.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => {
+      if (!aborted && !ended) timedOut = true;
+      kill();
+    }, opts.timeoutMs);
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      opts.signal.removeEventListener('abort', onAbort);
+      forget();
+      reject(err);
+    });
+    const flush = jsonLines(child.stdout, (ev) => {
+      if (!aborted && !timedOut && opts.isDone?.(ev)) ended = true;
+      opts.onEvent(ev);
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => {
+      stderr = (stderr + chunk).slice(-8000);
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      opts.signal.removeEventListener('abort', onAbort);
+      forget();
+      flush();
+      resolve({ code, signal, stderr, aborted, timedOut });
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(opts.stdin);
+  });
+}
+
+// A server that dies without draining leaves its agents' process groups running, and the next start
+// would answer the same messages again. So each group is recorded while it runs, and the next start stops what is left.
+
+interface GroupRecord {
+  pid: number;
+  /** The leader's start time, to tell it from a later process with its pid. */
+  startTime: string | null;
+  bootId: string | null;
+  cmd: string;
+  at: string;
+}
+
+function unlinkQuietly(path: string): void {
+  try {
+    unlinkSync(path);
+  } catch {}
+}
+
+function bootId(): string | null {
+  try {
+    return readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function processStartTime(pid: number): string | null {
+  if (process.platform === 'linux') {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      // Field 22 (starttime); the fields after the command's closing paren start at field 3.
+      return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function recordGroup(dir: string, pid: number, cmd: string): string | null {
+  const path = join(dir, `${pid}.json`);
+  try {
+    mkdirSync(dir, { recursive: true });
+    const rec: GroupRecord = { pid, startTime: processStartTime(pid), bootId: bootId(), cmd, at: nowIso() };
+    writeFileSync(path, JSON.stringify(rec));
+    return path;
+  } catch (err) {
+    log.warn('could not record an agent process group', { pid, err });
+    return null;
+  }
+}
+
+function groupAlive(pgid: number): boolean {
+  try {
+    process.kill(-pgid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Stop the recorded groups a previous server left running, and wait for them. A group is only signalled if it is
+ * still the same one: same boot, and its leader started when recorded (or the leader is gone but the group lives).
+ */
+export async function reapOrphanGroups(dir: string): Promise<number> {
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith('.json'));
+  } catch {
+    return 0;
+  }
+  const boot = bootId();
+  const groups: GroupRecord[] = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    let rec: GroupRecord;
+    try {
+      rec = JSON.parse(readFileSync(path, 'utf8')) as GroupRecord;
+    } catch {
+      unlinkQuietly(path);
+      continue;
+    }
+    unlinkQuietly(path);
+    const pid = Number(rec.pid);
+    if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid || !groupAlive(pid)) continue;
+    if (rec.bootId && boot && rec.bootId !== boot) continue; // rebooted since
+    const started = processStartTime(pid);
+    if (started !== null ? started !== rec.startTime : !(rec.bootId && boot)) continue; // another process now, or can't tell
+    groups.push(rec);
+  }
+  if (!groups.length) return 0;
+  for (const g of groups) {
+    log.warn('stopping an agent CLI that a previous server process left running (it died without draining), before its work runs again', {
+      pid: g.pid,
+      cmd: g.cmd,
+      since: g.at,
+    });
+    try {
+      process.kill(-g.pid, 'SIGTERM');
+    } catch {}
+  }
+  const waitFor = async (ms: number) => {
+    const end = Date.now() + ms;
+    while (groups.some((g) => groupAlive(g.pid)) && Date.now() < end) await new Promise((r) => setTimeout(r, 50));
+  };
+  await waitFor(5000);
+  for (const g of groups) {
+    if (!groupAlive(g.pid)) continue;
+    try {
+      process.kill(-g.pid, 'SIGKILL');
+    } catch {}
+  }
+  await waitFor(2000);
+  const left = groups.filter((g) => groupAlive(g.pid));
+  if (left.length) log.error('agent CLIs left by a previous server process would not stop', { pids: left.map((g) => g.pid) });
+  return groups.length;
+}
+
+export function failureMessage(label: string, run: JsonlRun, fallback: string | null): string {
+  if (run.aborted) return 'Stopped.';
+  if (run.timedOut) return `${label} timed out.`;
+  const tail = run.stderr.trim().split('\n').slice(-6).join('\n');
+  return fallback || tail || `${label} exited with code ${run.code}`;
+}
+
+/** `err` with how the CLI process ended (its last 20 stderr lines, at most 2000 characters), for the turn's log line. */
+export function withExit(err: ProviderError, run: JsonlRun): ProviderError {
+  const tail = run.stderr.trimEnd().split('\n').slice(-20).join('\n');
+  err.exit = { exitCode: run.code, signal: run.signal, timedOut: run.timedOut, stderrTail: tail.length > 2000 ? tail.slice(-2000) : tail };
+  return err;
+}

package/payload/server/src/providers/readiness.ts

@@ -0,0 +1,43 @@
+import type { BrainCheckProblem, BrainReadiness, BrainState } from '../../../shared/types.ts';
+import type { ProviderStatus } from './types.ts';
+
+/** A check older than this says nothing about now (the checker runs a new one after 5 minutes, when asked). */
+export const CHECK_OUTDATED_MS = 30 * 60_000;
+
+/** What a check's fixed word means for the brain's state. */
+const FROM_CHECK: Record<NonNullable<NonNullable<ProviderStatus['check']>['problem']>, BrainState> = {
+  'not-found': 'not-installed',
+  'not-runnable': 'unavailable',
+  'incompatible-version': 'unavailable',
+  'version-failed': 'unavailable',
+  'timed-out': 'unknown',
+  'login-unreadable': 'unknown',
+  'signed-out': 'signed-out',
+};
+
+/**
+ * How ready `p` is, from what its last check found and the usage limit its turns hit, if any. Ready only when a check
+ * ran within CHECK_OUTDATED_MS and confirmed it installed and signed in; never a promise that a turn will work.
+ */
+export function brainReadiness(p: ProviderStatus, usageLimitUntil: string | null, now = Date.now(), boot = ''): BrainReadiness {
+  const generation = p.check?.generation ?? 0;
+  const at = p.checkedAt ? Date.parse(p.checkedAt) : Number.NaN;
+  const out = (state: BrainState, problem: BrainCheckProblem | null): BrainReadiness => ({ state, problem, checkedAt: p.checkedAt, usageLimitUntil, boot, generation });
+  let state: BrainState;
+  let problem: BrainCheckProblem | null;
+  if (Number.isNaN(at)) [state, problem] = ['unknown', 'not-checked'];
+  // Stamped later than now: the clock was set back since, so how old the check is can't be told (the checker runs a
+  // new one when next asked).
+  else if (at > now) [state, problem] = ['unknown', 'clock-changed'];
+  else if (now - at > CHECK_OUTDATED_MS) [state, problem] = ['unknown', 'outdated'];
+  else if (p.check?.problem) [state, problem] = [FROM_CHECK[p.check.problem], p.check.problem];
+  // A provider whose check doesn't name its problem.
+  else if (!p.installed) [state, problem] = ['not-installed', 'not-found'];
+  else if (p.loggedIn === false) [state, problem] = ['signed-out', 'signed-out'];
+  else if (!p.available) [state, problem] = ['unavailable', 'unavailable'];
+  else if (p.loggedIn !== true) [state, problem] = ['unknown', 'login-unreadable'];
+  else [state, problem] = ['ready', null];
+  // A turn that hit the limit got past the sign-in, whatever the check could tell.
+  if (usageLimitUntil && (state === 'ready' || state === 'unknown')) return out('usage-limited', 'usage-limit');
+  return out(state, problem);
+}

package/payload/server/src/providers/sse.ts

@@ -0,0 +1,73 @@
+/** One server-sent event: its `event:` name ("message" when it has none) and its `data:` lines joined. */
+export interface SseEvent {
+  event: string;
+  data: string;
+}
+
+export class StreamError extends Error {
+  /** The stream ended (or broke) before the provider said its answer was complete. */
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/**
+ * The events of a streamed answer, in order. Bounded: at most `maxBytes` in all and `maxEvent` per event, and no
+ * gap longer than `idleMs` between chunks (a provider that went silent ends the turn rather than hold it).
+ */
+export async function* sseEvents(body: ReadableStream<Uint8Array>, opts: { maxBytes: number; maxEvent: number; idleMs: number; signal: AbortSignal }): AsyncGenerator<SseEvent> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = '';
+  let total = 0;
+  try {
+    for (;;) {
+      let timer: NodeJS.Timeout | undefined;
+      const idle = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new StreamError(`no data for ${Math.round(opts.idleMs / 1000)} s`)), opts.idleMs);
+      });
+      let chunk: ReadableStreamReadResult<Uint8Array>;
+      try {
+        chunk = await Promise.race([reader.read(), idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (chunk.done) break;
+      total += chunk.value.byteLength;
+      if (total > opts.maxBytes) throw new StreamError('the answer was larger than Botons reads');
+      buf += decoder.decode(chunk.value, { stream: true });
+      let at: number;
+      while ((at = boundary(buf)) >= 0) {
+        const block = buf.slice(0, at);
+        buf = buf.slice(at).replace(/^(\r?\n){2}|^\r\r/, '');
+        const ev = parse(block);
+        if (ev) yield ev;
+      }
+      if (buf.length > opts.maxEvent) throw new StreamError('one event of the answer was larger than Botons reads');
+    }
+    buf += decoder.decode();
+    const last = parse(buf);
+    if (last) yield last;
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+}
+
+function boundary(buf: string): number {
+  const m = /\r?\n\r?\n|\r\r/.exec(buf);
+  return m ? m.index : -1;
+}
+
+function parse(block: string): SseEvent | null {
+  let event = 'message';
+  const data: string[] = [];
+  for (const line of block.split(/\r?\n|\r/)) {
+    if (!line || line.startsWith(':')) continue;
+    const colon = line.indexOf(':');
+    const field = colon < 0 ? line : line.slice(0, colon);
+    const value = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+    if (field === 'event') event = value;
+    else if (field === 'data') data.push(value);
+  }
+  return data.length ? { event, data: data.join('\n') } : null;
+}

package/payload/server/src/providers/types.ts

@@ -0,0 +1,173 @@
+import type { AccessLevel, ProviderInfo, StepKind, TokenUsage, TurnStep } from '../../../shared/types.ts';
+import type { ModelEfforts } from '../../../shared/effort.ts';
+import type { AgentCli } from '../isolation.ts';
+import { nowIso } from '../util.ts';
+import type { SpendScope } from '../spend.ts';
+import type { CliCheckProblem } from './cli-check.ts';
+import type { FailureKind } from './failures.ts';
+
+export interface TurnRequest {
+  cwd: string;
+  sessionId: string | null;
+  systemPrompt: string;
+  prompt: string;
+  /** "" means the provider's default. */
+  model: string;
+  /** A level of shared/effort.ts for this provider; "" (or absent) means the provider's default, set by nothing. */
+  effort?: string;
+  access: AccessLevel;
+  images?: string[];
+  /** Paths a Workspace Boton must not read; empty for Full computer access. */
+  privatePaths: string[];
+  sharedDirs?: string[];
+  /** A sandboxed turn (webhook run, Workspace access) must not write the instruction files later turns load. */
+  protectInstructions?: boolean;
+  groupDir?: string;
+  env: Record<string, string>;
+  /** Their secrets go to the agent CLI only: never to argv, the log or the prompt. */
+  mcpServers?: TurnMcpServer[];
+  /** A 0700 folder for files holding those secrets; required with mcpServers. */
+  privateDir?: string;
+  askFirst?: { ask: string[]; allow: string[]; command: string; args: string[] };
+  /**
+   * A reply only (the summary a provider move asks the old session for): the model is given no tools at all, whatever
+   * the Boton's access. Only for a provider whose `toolFree` says it can; never with mcpServers or askFirst.
+   */
+  toolFree?: boolean;
+  /**
+   * For a provider that bills by the token (an API key): the turn whose spending caps apply (spend.ts). The CLIs
+   * ignore it: their cost isn't Botons' to bound.
+   */
+  spend?: SpendScope;
+  /** The `botons` CLI, for a provider whose tools Botons runs itself (`serverTools`). */
+  botonCli?: string;
+  signal: AbortSignal;
+  timeoutMs: number;
+  onActivity: (activity: string) => void;
+  /** All of the message being written so far; a new message starts over. */
+  onText?: (textSoFar: string) => void;
+  onStep?: (step: TurnStep) => void;
+  /** Each MCP tool call on one of `mcpServers` that finished, with its structured result (never display text). */
+  onToolResult?: (obs: ToolObservation) => void;
+}
+
+export interface ToolObservation {
+  /** The CLI's id for the call. */
+  callId: string;
+  /** The server's name in this turn (a key of mcpServers). */
+  server: string;
+  tool: string;
+  /** False for an error result, or one the CLI marks failed. */
+  ok: boolean;
+  /** The result's structuredContent, or its JSON text block when that is all the CLI passes on; else null. */
+  structured: Record<string, unknown> | null;
+}
+
+export function step(kind: StepKind, label: string, detail: string): TurnStep {
+  return { kind, label, detail, at: nowIso() };
+}
+
+export interface TurnUsage extends TokenUsage {
+  numTurns?: number;
+  model?: string;
+}
+
+/** How long the CLI gives a server to start and to run one tool, in seconds; the CLI's defaults when left out. */
+export interface McpTimeouts {
+  startupTimeoutSec?: number;
+  toolTimeoutSec?: number;
+}
+
+export type TurnMcpServer =
+  | ({
+      name: string;
+      kind: 'stdio';
+      command: string;
+      args: string[];
+      env: Record<string, string>;
+      cwd?: string;
+      /** What must not come back out in text, when not `env`'s values (a local connector's, in its launch file). */
+      secrets?: string[];
+    } & McpTimeouts)
+  | ({ name: string; kind: 'http'; url: string; headers: Record<string, string>; sse?: boolean } & McpTimeouts);
+
+/**
+ * What the CLI showed of one of the turn's MCP servers. Only servers it said something about are listed: Claude Code
+ * reports each one's status and tools when the turn starts; Codex reports nothing, so only a tool call it ran shows
+ * a server started.
+ */
+export interface McpStartup {
+  name: string;
+  started: boolean;
+  /** The tools the CLI listed for it; null when the CLI doesn't list them. */
+  tools: string[] | null;
+  /** Why it didn't start (or may not have), as the owner and the Boton are told. */
+  reason?: string;
+}
+
+export interface TurnResult {
+  sessionId: string | null;
+  text: string;
+  /** Errors the CLI reported during a turn that still completed. */
+  warnings?: string[];
+  usage?: TurnUsage | null;
+  mcpStartup?: McpStartup[];
+}
+
+export class ProviderError extends Error {
+  /**
+   * Only when the provider no longer has the session and the run did nothing
+   * else: the engine retries in a new session, so a false positive runs the work twice.
+   */
+  sessionLost: boolean;
+  kind: FailureKind;
+  retryAt: Date | null;
+  exit?: { exitCode: number | null; signal: string | null; timedOut: boolean; stderrTail: string };
+  usage?: TurnUsage | null;
+  mcpStartup?: McpStartup[];
+  constructor(message: string, sessionLost = false, info: { kind?: FailureKind; retryAt?: Date | null } = {}) {
+    super(message);
+    this.sessionLost = sessionLost;
+    this.kind = info.kind ?? 'other';
+    this.retryAt = info.retryAt ?? null;
+  }
+}
+
+export interface Provider {
+  id: string;
+  label: string;
+  cli?: AgentCli;
+  info(): Promise<ProviderStatus>;
+  /**
+   * What info() would say from the checks already done, without running one (CliChecker.peek): null checkedAt before
+   * the first. Absent: info() itself runs nothing.
+   */
+  snapshot?(): ProviderStatus;
+  /** Drop cached checks, so the next info() runs them again. */
+  recheck?(): void;
+  runTurn(req: TurnRequest): Promise<TurnResult>;
+  /** Which of a turn's MCP servers this CLI can be given, and why the others can't. */
+  fitMcpServers?(servers: TurnMcpServer[]): { servers: TurnMcpServer[]; skipped: { name: string; reason: string }[] };
+  askFirst?: boolean;
+  /**
+   * Its CLI can run a turn with no tools at all (TurnRequest.toolFree): every built-in tool, MCP tool, skill and
+   * command taken away, not only fenced in by a sandbox. Absent: it can't, and a toolFree turn is refused.
+   */
+  toolFree?: boolean;
+  /** What the CLI's own model list says `model` takes; null when it doesn't list levels for it (see shared/effort.ts). */
+  modelEfforts?(model: string): ModelEfforts | null;
+  /**
+   * No CLI: Botons runs the agent loop and every tool itself (an API key brain, providers/api-brain.ts), the turn's
+   * Botons connectors included, which the server calls on the Boton's behalf.
+   */
+  serverTools?: boolean;
+}
+
+/**
+ * `effort` left out: the registry fills it in from shared/effort.ts. `readiness` is the registry's too, from `check`:
+ * what the provider's own check found, if it runs one.
+ */
+export type ProviderStatus = Omit<ProviderInfo, 'lastSuccessAt' | 'lastError' | 'effort' | 'readiness'> & {
+  effort?: ProviderInfo['effort'];
+  check?: { problem: CliCheckProblem | null; generation: number };
+};

package/payload/server/src/rates.ts

@@ -0,0 +1,128 @@
+import type { TokenUsage } from '../../shared/types.ts';
+
+/*
+ * What API-key turns cost, as Botons estimates it: the tokens each answer reports times these per-model rates. The
+ * rates are copied from the providers' own price pages (the sources below, on the date given), standard tier, no
+ * batch, regional, data-residency, fast or priority pricing (Botons asks for none of those). A model not listed here,
+ * or past a rate's `until`, has no known price: its cost is unknown, never guessed from a similar name, and a Boton
+ * or routine with a spending cap won't run on it. The estimate is not the provider's bill: the bill is the provider's.
+ */
+
+/** US dollars per million tokens. `cacheRead`/`cacheWrite` null: the page lists none (charged as input, if ever). */
+export interface Rate {
+  input: number;
+  output: number;
+  cacheRead: number | null;
+  cacheWrite: number | null;
+}
+
+export interface ModelRate {
+  provider: 'anthropic' | 'openai';
+  model: string;
+  rate: Rate;
+  /** A prompt (all its input tokens, cached ones included) over `over` tokens is priced at `rate` instead. */
+  long?: { over: number; rate: Rate };
+  /** The last day these rates hold (a promotion's end); after it the price is unknown. */
+  until?: string;
+}
+
+export const RATE_SOURCES = {
+  anthropic: { url: 'https://platform.claude.com/docs/en/about-claude/pricing', checked: '2026-11-07', cacheWrite: '5-minute cache writes (Botons asks for no longer)' },
+  openai: { url: 'https://developers.openai.com/api/docs/pricing', checked: '2026-11-07', cacheWrite: '30-minute cache writes (Botons asks for no longer)' },
+} as const;
+
+const r = (input: number, output: number, cacheRead: number | null, cacheWrite: number | null): Rate => ({ input, output, cacheRead, cacheWrite });
+
+const ANTHROPIC: Record<string, Omit<ModelRate, 'provider' | 'model'>> = {
+  'claude-fable-5-1': { rate: r(10, 50, 0.25, 12.5) },
+  'claude-mythos-5-1': { rate: r(10, 50, 0.25, 12.5) },
+  'claude-fable-5': { rate: r(10, 50, 1, 12.5) },
+  'claude-opus-5-5': { rate: r(4, 20, 0.2, 5) },
+  'claude-opus-5': { rate: r(5, 25, 0.5, 6.25) },
+  'claude-opus-4-8': { rate: r(5, 25, 0.5, 6.25) },
+  'claude-opus-4-7': { rate: r(5, 25, 0.5, 6.25) },
+  'claude-opus-4-6': { rate: r(5, 25, 0.5, 6.25) },
+  'claude-sonnet-5-5': { rate: r(2, 10, 0.1, 2.5) },
+  'claude-sonnet-5': { rate: r(2, 10, 0.2, 2.5) },
+  'claude-sonnet-4-6': { rate: r(3, 15, 0.3, 3.75) },
+  'claude-haiku-5-5': { rate: r(0.1, 0.5, 0.01, 0.125), long: { over: 100_000, rate: r(0.5, 2.5, 0.05, 0.625) } },
+  'claude-haiku-4-5': { rate: r(1, 5, 0.1, 1.25) },
+};
+
+const LONG_OPENAI = 272_000;
+const OPENAI: Record<string, Omit<ModelRate, 'provider' | 'model'>> = {
+  'gpt-6-astra': { rate: r(10, 50, 1, 12.5), long: { over: LONG_OPENAI, rate: r(20, 75, 2, 25) } },
+  'gpt-6.1-sol': { rate: r(2, 10, 0.1, 2.5), long: { over: LONG_OPENAI, rate: r(4, 15, 0.2, 5) } },
+  'gpt-6.1-terra': { rate: r(1, 5, 0.05, 1.25), long: { over: LONG_OPENAI, rate: r(2, 7.5, 0.1, 2.5) } },
+  'gpt-6-luna': { rate: r(0.1, 0.5, 0.01, 0.125), long: { over: LONG_OPENAI, rate: r(0.2, 0.75, 0.02, 0.25) } },
+  'gpt-6-sol': { rate: r(2, 10, 0.2, 2.5), long: { over: LONG_OPENAI, rate: r(4, 15, 0.4, 5) } },
+  // A promotional price, until the end of 2026-11-30 as the page says.
+  'gpt-5.6-sol': { rate: r(4, 20, 0.4, 5), long: { over: LONG_OPENAI, rate: r(8, 30, 0.8, 10) }, until: '2026-11-30' },
+  'gpt-5.6-terra': { rate: r(2, 12, 0.2, 2.5), long: { over: LONG_OPENAI, rate: r(4, 18, 0.4, 5) } },
+  'gpt-5.6-luna': { rate: r(0.2, 1.2, 0.02, 0.25), long: { over: LONG_OPENAI, rate: r(0.4, 1.8, 0.04, 0.5) } },
+  'gpt-5.5': { rate: r(5, 30, 0.5, null), long: { over: LONG_OPENAI, rate: r(10, 45, 1, null) } },
+  'gpt-5.5-pro': { rate: r(30, 180, null, null), long: { over: LONG_OPENAI, rate: r(60, 270, null, null) } },
+  'gpt-5.4': { rate: r(2.5, 15, 0.25, null), long: { over: LONG_OPENAI, rate: r(5, 22.5, 0.5, null) } },
+  'gpt-5.4-pro': { rate: r(30, 180, null, null), long: { over: LONG_OPENAI, rate: r(60, 270, null, null) } },
+  'gpt-5.4-mini': { rate: r(0.75, 4.5, 0.075, null) },
+  'gpt-5.4-nano': { rate: r(0.2, 1.25, 0.02, null) },
+  'gpt-5.2': { rate: r(1.75, 14, 0.175, null) },
+  'gpt-5.2-pro': { rate: r(21, 168, null, null) },
+  'gpt-5.1': { rate: r(1.25, 10, 0.125, null) },
+  'gpt-5': { rate: r(1.25, 10, 0.125, null) },
+  'gpt-5-mini': { rate: r(0.25, 2, 0.025, null) },
+  'gpt-5-nano': { rate: r(0.05, 0.4, 0.005, null) },
+  'gpt-5-pro': { rate: r(15, 120, null, null) },
+  'gpt-4.1': { rate: r(2, 8, 0.5, null) },
+  'gpt-4.1-mini': { rate: r(0.4, 1.6, 0.1, null) },
+  'gpt-4o': { rate: r(2.5, 10, 1.25, null) },
+  'gpt-4o-mini': { rate: r(0.15, 0.6, 0.075, null) },
+  'o3-pro': { rate: r(20, 80, null, null) },
+  o3: { rate: r(2, 8, 0.5, null) },
+};
+
+/** The rates for exactly `model` (no prefix or snapshot matching), or null when its price isn't known. */
+export function rateFor(provider: 'anthropic' | 'openai', model: string, now = new Date()): ModelRate | null {
+  const table = provider === 'anthropic' ? ANTHROPIC : OPENAI;
+  const found = Object.hasOwn(table, model) ? table[model] : undefined;
+  if (!found) return null;
+  if (found.until && now.toISOString().slice(0, 10) > found.until) return null;
+  return { provider, model, ...found };
+}
+
+const PER = 1_000_000;
+
+/** The rate a prompt of `promptTokens` input tokens (cached ones included) pays. */
+function rateAt(m: ModelRate, promptTokens: number): Rate {
+  return m.long && promptTokens > m.long.over ? m.long.rate : m.rate;
+}
+
+/** The estimate for one answer's usage; `inputTokens` excludes cache reads and writes (TokenUsage's meaning). */
+export function costOf(m: ModelRate, u: Pick<TokenUsage, 'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheWriteTokens'>): number {
+  const prompt = u.inputTokens + u.cacheReadTokens + u.cacheWriteTokens;
+  const rate = rateAt(m, prompt);
+  const usd = (u.inputTokens * rate.input + u.cacheReadTokens * (rate.cacheRead ?? rate.input) + u.cacheWriteTokens * (rate.cacheWrite ?? rate.input) + u.outputTokens * rate.output) / PER;
+  return round(usd);
+}
+
+/**
+ * The most one request can cost: every one of at most `inputTokens` input tokens at the dearest input rate (a cache
+ * write costs more than plain input), and `maxOutputTokens` (the cap the request sets, thinking included) at the
+ * output rate, at the long-context rate if the prompt could be long.
+ */
+export function mostOf(m: ModelRate, inputTokens: number, maxOutputTokens: number): number {
+  const rate = rateAt(m, inputTokens);
+  const dearest = Math.max(rate.input, rate.cacheWrite ?? 0, rate.cacheRead ?? 0);
+  return round((inputTokens * dearest + maxOutputTokens * rate.output) / PER);
+}
+
+/** The output tokens `usd` pays for at most, after `inputTokens` at the dearest input rate; 0 when it can't. */
+export function outputFor(m: ModelRate, inputTokens: number, usd: number): number {
+  const rate = rateAt(m, inputTokens);
+  const dearest = Math.max(rate.input, rate.cacheWrite ?? 0, rate.cacheRead ?? 0);
+  const left = usd * PER - inputTokens * dearest;
+  return left <= 0 ? 0 : Math.floor(left / rate.output);
+}
+
+/** Dollars are summed as floats; rounded to a millionth of a cent so sums compare as they read. */
+export const round = (usd: number) => Math.round(usd * 1e8) / 1e8;