getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/spend.ts

@@ -0,0 +1,255 @@
+import { randomUUID } from 'node:crypto';
+import type { DatabaseSync } from 'node:sqlite';
+import type { SpendingInput, SpendingView } from '../../shared/types.ts';
+import { log } from './log.ts';
+import { type ModelRate, mostOf, outputFor, round } from './rates.ts';
+import { zonedToUtc } from './schedule.ts';
+import { HttpError } from './store.ts';
+
+/*
+ * Spending caps on API-key turns, kept on Botons' own estimate (rates.ts), never the provider's bill: a Boton may
+ * have a daily cap (from midnight in its time zone) and each of its routines a cap per run (all the run's attempts).
+ *
+ * The account is one row per request to a model, in api_requests, never per turn:
+ * - A request's period is the moment it was reserved, just before it was sent (the server's clock, as a UTC instant):
+ *   it counts on the day that moment falls in, in the Boton's time zone as it is when the day is read. A turn that
+ *   runs past midnight counts its later requests on the new day, and a hold made before midnight stays on its own day.
+ *   A day counts every request from its midnight on, with no end: after the clock is set back, requests stamped later
+ *   still count on today, never dropped.
+ * - Before each request, in one transaction: the caps that apply are read as they are now (a cap added, lowered or
+ *   removed since the turn began counts from its next request), and what is left under them; the most the request
+ *   can cost (every input token at the dearest input rate, its output cap at the output rate) is written as its row.
+ *   If that doesn't fit, its output cap is lowered to fit; if not even a small answer fits, it isn't sent. A request
+ *   already sent stays counted however the caps change after.
+ * - When its answer comes, the row becomes what its reported tokens cost. A request whose tokens are unknown (the
+ *   answer broke off, was stopped, or reported no valid usage) stays held at its most: the provider may have billed
+ *   it. One refused before anything was generated is released. A row still reserved when the server starts was the
+ *   process's that is gone: it is held, never released.
+ * - A model with no known rate can't be kept to a cap: with a cap set, its requests are refused, and so are a capped
+ *   Boton's requests on a day (or in a run) that already has one with no known price.
+ * The provider's bill can still differ (its rounding, rates changed since rates.ts was checked, tokens Botons can't see);
+ * a cap bounds Botons' estimate, not the bill.
+ */
+
+export const API_BRAINS = ['anthropic-api', 'openai-api'] as const;
+export const MAX_CAP_USD = 100_000;
+/** Settled rows older than this go (no cap looks back further than a run). */
+const KEEP_DAYS = 400;
+
+export const SPEND_RULES =
+  'Caps count Botons’ own estimate of API-key requests (the tokens each answer reports times the published rates), not your provider’s bill. Each request counts on the day it was sent. Before each one the most it could cost is set aside, under the caps as they are then; it is sent only if that fits in what is left. A request whose answer was cut off or stopped stays counted at that most. A change to a cap applies from the next request; one already sent stays counted. Requests on a model with no known price don’t run while a cap is set.';
+
+const capKey = (kind: 'bot' | 'routine', id: string) => `spendCap:${kind}:${id}`;
+
+/** What a row counts: its cost once settled, its most while reserved or held, nothing once released. */
+const COUNTED = `case state when 'settled' then coalesce(cost_usd, 0) when 'released' then 0 else coalesce(reserved_usd, 0) end`;
+/** A row with no known price that may have been billed. */
+const UNPRICED = `case when state != 'released' and reserved_usd is null and cost_usd is null then 1 else 0 end`;
+
+export class CapError extends Error {}
+
+export interface SpendScope {
+  botId: string;
+  turnId: string;
+  runId: string | null;
+  routineId: string | null;
+}
+
+export interface ReserveAsk {
+  provider: string;
+  model: string;
+  /** null: no known price (then nothing can be set aside, and no cap may apply). */
+  rate: ModelRate | null;
+  /** At most this many input tokens. */
+  inputTokens: number;
+  maxOutput: number;
+  /** Below this output cap a request isn't worth sending. */
+  minOutput: number;
+}
+
+/** One request's row. Each of settle, hold and release acts once, and only on a row still reserved. */
+export interface Reservation {
+  /** The output cap it was reserved at (lowered to fit a cap). */
+  maxOutput: number;
+  /** What was set aside; null with no known price. */
+  usd: number | null;
+  settle(usd: number | null): void;
+  hold(): void;
+  release(): void;
+}
+
+export class Spending {
+  #db: DatabaseSync;
+  #now: () => Date;
+
+  constructor(db: DatabaseSync, opts: { now?: () => Date } = {}) {
+    this.#db = db;
+    this.#now = opts.now ?? (() => new Date());
+    // Reserved by a process that is gone: it may have been sent and billed.
+    const n = Number(this.#db.prepare("update api_requests set state = 'held' where state = 'reserved'").run().changes);
+    if (n) log.warn('API requests a stopped server left reserved are held at their most', { requests: n });
+  }
+
+  #cap(kind: 'bot' | 'routine', id: string | null): number | null {
+    if (!id) return null;
+    const row = this.#db.prepare('select value from settings where key = ?').get(capKey(kind, id)) as { value: string } | undefined;
+    const v = row ? Number(row.value) : Number.NaN;
+    return Number.isFinite(v) && v >= 0 ? v : null;
+  }
+
+  #setCap(kind: 'bot' | 'routine', id: string, usd: number | null) {
+    if (usd === null) this.#db.prepare('delete from settings where key = ?').run(capKey(kind, id));
+    else this.#db.prepare('insert into settings(key, value) values (?, ?) on conflict(key) do update set value = excluded.value').run(capKey(kind, id), String(usd));
+  }
+
+  /** Midnight of `now`'s day in `tz`, as an ISO time (rows' `at` compare as text). */
+  dayStart(tz: string, now = this.#now()): string {
+    const parts = new Intl.DateTimeFormat('en-US', { timeZone: tz, year: 'numeric', month: 'numeric', day: 'numeric' }).formatToParts(now);
+    const get = (t: string) => Number(parts.find((p) => p.type === t)?.value);
+    return zonedToUtc(get('year'), get('month'), get('day'), 0, 0, tz).toISOString();
+  }
+
+  #today(botId: string): { spent: number; unpriced: number; since: string } {
+    const since = this.dayStart(this.#timezone(botId));
+    const r = this.#db.prepare(`select coalesce(sum(${COUNTED}), 0) as spent, coalesce(sum(${UNPRICED}), 0) as unpriced from api_requests where bot_id = ? and at >= ?`).get(botId, since) as {
+      spent: number;
+      unpriced: number;
+    };
+    return { spent: round(Number(r.spent)), unpriced: Number(r.unpriced), since };
+  }
+
+  #run(runId: string): { spent: number; unpriced: number } {
+    const r = this.#db.prepare(`select coalesce(sum(${COUNTED}), 0) as spent, coalesce(sum(${UNPRICED}), 0) as unpriced from api_requests where run_id = ?`).get(runId) as { spent: number; unpriced: number };
+    return { spent: round(Number(r.spent)), unpriced: Number(r.unpriced) };
+  }
+
+  #timezone(botId: string): string {
+    const r = this.#db.prepare('select timezone from bots where id = ?').get(botId) as { timezone: string } | undefined;
+    return r?.timezone || 'UTC';
+  }
+
+  view(botId: string): SpendingView {
+    const today = this.#today(botId);
+    const routines = this.#db.prepare('select id, name from routines where bot_id = ? order by created_at').all(botId) as { id: string; name: string }[];
+    return {
+      botId,
+      dailyCapUsd: this.#cap('bot', botId),
+      spentTodayUsd: today.spent,
+      unpricedToday: today.unpriced,
+      dayStartedAt: today.since,
+      routines: routines.map((x) => ({ id: String(x.id), name: String(x.name), perRunCapUsd: this.#cap('routine', String(x.id)) })),
+      rules: SPEND_RULES,
+    };
+  }
+
+  update(botId: string, input: SpendingInput): SpendingView {
+    const usd = (v: unknown, field: string): number | null => {
+      if (v === null) return null;
+      if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > MAX_CAP_USD) throw new HttpError(400, `${field} must be a number of US dollars from 0 to ${MAX_CAP_USD}, or null for no cap`);
+      return round(v);
+    };
+    const changes: [kind: 'bot' | 'routine', id: string, usd: number | null][] = [];
+    if (input?.dailyCapUsd !== undefined) changes.push(['bot', botId, usd(input.dailyCapUsd, 'dailyCapUsd')]);
+    if (input?.routines !== undefined) {
+      if (!input.routines || typeof input.routines !== 'object' || Array.isArray(input.routines)) throw new HttpError(400, 'routines must map routine ids to a cap or null');
+      for (const [id, v] of Object.entries(input.routines)) {
+        const own = this.#db.prepare('select 1 from routines where id = ? and bot_id = ?').get(id, botId);
+        if (!own) throw new HttpError(404, `No routine ${id} on this Boton`);
+        changes.push(['routine', id, usd(v, `routines.${id}`)]);
+      }
+    }
+    for (const [kind, id, v] of changes) this.#setCap(kind, id, v);
+    log.info('spending caps changed', { botId, caps: changes.map(([kind, id, v]) => ({ kind, id, usd: v })) });
+    return this.view(botId);
+  }
+
+  /**
+   * The caps a configuration import gives a Boton it has just made, inside the import's transaction. Only ever on a
+   * Boton with no cap and no account here yet: an import never raises, clears or restarts caps or spending a Boton
+   * already has (a Boton made anew starts at $0, as one the owner adds by hand does). Anything else throws, and the
+   * import rolls back.
+   */
+  importCaps(botId: string, daily: number | null, routines: [routineId: string, usd: number][]): void {
+    const db = this.#db;
+    if (!db.isTransaction) throw new Error('importCaps runs inside the import transaction');
+    const ok = (v: number) => Number.isFinite(v) && v >= 0 && v <= MAX_CAP_USD;
+    if ((daily !== null && !ok(daily)) || routines.some(([, v]) => !ok(v))) throw new Error('an imported spending cap is out of range');
+    const routineIds = this.#db.prepare('select id from routines where bot_id = ?').all(botId).map((r) => String((r as { id: string }).id));
+    const keys = [capKey('bot', botId), ...routineIds.map((id) => capKey('routine', id))];
+    const had = keys.some((k) => db.prepare('select 1 from settings where key = ?').get(k));
+    const counted = db.prepare('select 1 from api_requests where bot_id = ? limit 1').get(botId);
+    if (had || counted) throw new Error('an import only gives caps to a Boton it has just made');
+    for (const [id] of routines) if (!routineIds.includes(id)) throw new Error('an imported routine cap names a routine of another Boton');
+    if (daily !== null) this.#setCap('bot', botId, round(daily));
+    for (const [id, v] of routines) this.#setCap('routine', id, round(v));
+  }
+
+  /** Caps of Botons and routines that no longer exist go, and settled rows past any cap's reach. */
+  prune(): void {
+    this.#db.exec(
+      `delete from settings where (key like 'spendCap:bot:%' and substr(key, 14) not in (select id from bots))
+         or (key like 'spendCap:routine:%' and substr(key, 18) not in (select id from routines))`,
+    );
+    const before = new Date(this.#now().getTime() - KEEP_DAYS * 86_400_000).toISOString();
+    this.#db.prepare("delete from api_requests where at < ? and state in ('settled', 'released')").run(before);
+  }
+
+  /**
+   * Sets aside the most the next request can cost under the caps as they are now, as its own row, or throws CapError
+   * (nothing written). One transaction: no other request is counted between the read and the write.
+   */
+  reserve(scope: SpendScope, ask: ReserveAsk): Reservation {
+    const db = this.#db;
+    db.exec('begin immediate');
+    let row: { id: string; maxOutput: number; usd: number | null };
+    try {
+      row = this.#reserve(scope, ask);
+      db.exec('commit');
+    } catch (err) {
+      if (db.isTransaction) db.exec('rollback');
+      throw err;
+    }
+    const end = (state: 'settled' | 'held' | 'released', cost: number | null) =>
+      db.prepare("update api_requests set state = ?, cost_usd = ?, ended_at = ? where id = ? and state = 'reserved'").run(state, cost === null ? null : round(cost), this.#now().toISOString(), row.id);
+    return {
+      maxOutput: row.maxOutput,
+      usd: row.usd,
+      // Tokens unknown: held at its most (or, with no known price, an unpriced request that may have been billed).
+      settle: (usd) => (usd === null ? end('held', null) : end('settled', usd)),
+      hold: () => end('held', null),
+      release: () => end('released', null),
+    };
+  }
+
+  #reserve(scope: SpendScope, ask: ReserveAsk): { id: string; maxOutput: number; usd: number | null } {
+    const daily = this.#cap('bot', scope.botId);
+    const perRun = scope.runId ? this.#cap('routine', scope.routineId) : null;
+    const capped = daily !== null || perRun !== null;
+    if (capped && !ask.rate) throw new CapError('its model has no known price in Botons, so its spending cap can’t be kept. Pick a model with a known price, or remove the cap.');
+    let left = Number.POSITIVE_INFINITY;
+    let which = '';
+    if (daily !== null) {
+      const today = this.#today(scope.botId);
+      if (today.unpriced > 0) throw new CapError(`today already has ${today.unpriced} API-key request${today.unpriced > 1 ? 's' : ''} with no known price, so the daily cap can’t be kept until tomorrow.`);
+      if (daily - today.spent < left) [left, which] = [daily - today.spent, `the Boton’s daily cap of $${daily}`];
+    }
+    if (perRun !== null && scope.runId) {
+      const run = this.#run(scope.runId);
+      if (run.unpriced > 0) throw new CapError('this run already has a request with no known price, so the routine’s cap can’t be kept.');
+      if (perRun - run.spent < left) [left, which] = [perRun - run.spent, `the routine’s cap of $${perRun} a run`];
+    }
+    let maxOutput = ask.maxOutput;
+    if (ask.rate && capped) {
+      const fits = outputFor(ask.rate, ask.inputTokens, round(left));
+      if (fits < ask.minOutput) throw new CapError(`the next request could cost more than the $${Math.max(0, left).toFixed(4)} left under ${which}.`);
+      maxOutput = Math.min(maxOutput, fits);
+    }
+    const usd = ask.rate ? mostOf(ask.rate, ask.inputTokens, maxOutput) : null;
+    if (usd !== null && usd > left + 1e-9) throw new CapError(`the next request could cost up to $${usd.toFixed(4)}, more than the $${Math.max(0, left).toFixed(4)} left under ${which}.`);
+    const id = `req_${randomUUID()}`;
+    this.#db
+      .prepare("insert into api_requests (id, bot_id, turn_id, run_id, routine_id, provider, model, at, reserved_usd, cost_usd, state) values (?, ?, ?, ?, ?, ?, ?, ?, ?, null, 'reserved')")
+      .run(id, scope.botId, scope.turnId, scope.runId, scope.routineId, ask.provider, ask.model, this.#now().toISOString(), usd);
+    return { id, maxOutput, usd };
+  }
+}

package/payload/server/src/ssrf.ts

@@ -0,0 +1,126 @@
+import { lookup as dnsLookup, type LookupAddress } from 'node:dns';
+import { BlockList, isIP, type LookupFunction } from 'node:net';
+import { networkInterfaces } from 'node:os';
+
+const DENY = new BlockList();
+for (const [net, bits] of [
+  ['0.0.0.0', 8], // "this network"
+  ['10.0.0.0', 8],
+  ['100.64.0.0', 10], // carrier-grade NAT, and Tailscale's addresses
+  ['127.0.0.0', 8],
+  ['169.254.0.0', 16], // link-local, and cloud metadata services
+  ['172.16.0.0', 12],
+  ['192.0.0.0', 24],
+  ['192.0.2.0', 24],
+  ['192.168.0.0', 16],
+  ['198.18.0.0', 15],
+  ['198.51.100.0', 24],
+  ['203.0.113.0', 24],
+  ['224.0.0.0', 4], // multicast
+  ['240.0.0.0', 4], // reserved, and broadcast
+] as const) {
+  DENY.addSubnet(net, bits, 'ipv4');
+}
+for (const [net, bits] of [
+  ['::', 128],
+  ['::1', 128],
+  ['64:ff9b::', 96], // NAT64: could lead to any IPv4 address
+  ['100::', 64],
+  ['2001:db8::', 32],
+  ['fc00::', 7], // unique local, and Tailscale's IPv6 addresses
+  ['fe80::', 10],
+  ['ff00::', 8],
+] as const) {
+  DENY.addSubnet(net, bits, 'ipv6');
+}
+
+/** BOTONS_CALLBACK_ALLOW, parsed. */
+interface Allowance {
+  addresses: BlockList;
+  names: Set<string>;
+}
+
+const family = (ip: string) => (isIP(ip) === 6 ? 'ipv6' : 'ipv4');
+
+export function allowance(entries: string[]): Allowance {
+  const addresses = new BlockList();
+  const names = new Set<string>();
+  for (const entry of entries) {
+    const [ip, bits] = entry.split('/');
+    if (!isIP(ip)) names.add(entry.toLowerCase());
+    else if (bits === undefined) addresses.addAddress(ip, family(ip));
+    else addresses.addSubnet(ip, Number(bits), family(ip));
+  }
+  return { addresses, names };
+}
+
+/** Why the server must not connect to `ip`, or null if it may. */
+export function refusedAddress(ip: string, allow: Allowance): string | null {
+  const plain = ip.toLowerCase().replace(/^\[|\]$/g, '').replace(/%.*$/, '');
+  if (!isIP(plain)) return 'not an IP address';
+  if (allow.addresses.check(plain, family(plain))) return null;
+  // An IPv4 address written as IPv6 (::ffff:127.0.0.1) is judged as the IPv4 one.
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(plain)?.[1];
+  if (mapped) return refusedAddress(mapped, allow);
+  if (DENY.check(plain, family(plain))) return 'a loopback, private, link-local or reserved address';
+  const own = Object.values(networkInterfaces()).flat().some((i) => i?.address.toLowerCase().replace(/%.*$/, '') === plain);
+  if (own) return "this machine's own address";
+  return null;
+}
+
+const ALLOW_HINT = 'BOTONS_CALLBACK_ALLOW can allow it';
+
+const LOCAL_NAME = /(^|\.)localhost\.?$/i;
+
+/** Why a callback URL is refused as written, or null. Names are checked on what they resolve to when connecting. */
+export function refusedUrl(raw: string, allow: Allowance): string | null {
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return 'callbackUrl must be an http:// or https:// URL';
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return 'callbackUrl must be an http:// or https:// URL';
+  if (u.username || u.password) return 'callbackUrl must not contain a user name or password';
+  const host = u.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (allow.names.has(host)) return null;
+  if (isIP(host)) {
+    const why = refusedAddress(host, allow);
+    return why ? `callbackUrl can't point at ${host}: ${why} (${ALLOW_HINT})` : null;
+  }
+  if (LOCAL_NAME.test(host)) return `callbackUrl can't point at ${host}: this machine (${ALLOW_HINT})`;
+  return null;
+}
+
+/** A `lookup` for http.request that refuses a name if any of its addresses is refused, so a later DNS answer can't slip past an earlier check. */
+export function guardedLookup(allow: Allowance): LookupFunction {
+  return (hostname, options, callback) => {
+    dnsLookup(hostname, { ...options, all: true }, (err, addresses: LookupAddress[]) => {
+      if (err) return callback(err, '', 0);
+      const allowedName = allow.names.has(hostname.toLowerCase());
+      for (const a of allowedName ? [] : addresses) {
+        const why = refusedAddress(a.address, allow);
+        if (why) return callback(Object.assign(new Error(`${hostname} resolves to ${a.address}, ${why} (${ALLOW_HINT})`), { code: 'EREFUSEDADDRESS' }), '', 0);
+      }
+      if (options.all) return (callback as unknown as (err: null, addresses: LookupAddress[]) => void)(null, addresses);
+      callback(null, addresses[0].address, addresses[0].family);
+    });
+  };
+}
+
+/** Check a callback URL before saving it. A name that doesn't resolve now passes: every send checks it again. */
+export async function checkCallbackUrl(raw: string, allowEntries: string[]): Promise<string | null> {
+  const allow = allowance(allowEntries);
+  const refused = refusedUrl(raw, allow);
+  if (refused) return refused;
+  const host = new URL(raw).hostname.replace(/^\[|\]$/g, '');
+  if (isIP(host) || allow.names.has(host.toLowerCase())) return null;
+  const lookup = guardedLookup(allow);
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(null), 3000);
+    lookup(host, { all: true }, (err) => {
+      clearTimeout(timer);
+      resolve((err as NodeJS.ErrnoException | null)?.code === 'EREFUSEDADDRESS' ? `callbackUrl can't point at ${host}: ${err!.message}` : null);
+    });
+  });
+}

package/payload/server/src/starter-gate.ts

@@ -0,0 +1,168 @@
+import { createHmac } from 'node:crypto';
+import type { Routine, RoutineRun, StarterRoutineGate } from '../../shared/types.ts';
+import type { Connectors } from './connectors.ts';
+import type { Skills } from './skills.ts';
+import { type BotRecord, HttpError, type StarterRecord, type Store } from './store.ts';
+import { nowIso } from './util.ts';
+
+/*
+ * When a starter's routine may be turned on. Installing a starter saves a record (Store.starterRecord) listing its
+ * routines as pending; while one is, Store.updateRoutine refuses to turn it on for anyone, so a PATCH, the `botons`
+ * CLI, the Routines panel or a copy of the Boton can't. Only activate() turns it on: for the owner (its route is
+ * theirs alone), when the latest test run finished without an error on exactly the settings it has now, or when the
+ * owner overrides that. Either way it is then an ordinary routine.
+ *
+ * "Exactly the settings": a test run's turn notes what it ran on (noteTest) as keyed hashes of each part below, taken
+ * from the very records the turn used. Turning on compares them with the same parts computed now, in one synchronous
+ * step with the enabling write, so nothing can change between the comparison and the grant. A finished test run is no
+ * proof its output was right, only that the brain's process ended without an error on these settings: the owner reads
+ * its reply. A test run is a real turn told to act as a dry run; nothing here enforces that.
+ */
+
+/** What a test run ran on, part by part, for saying which changed since. */
+export const PARTS = {
+  boton: "the Boton's settings (brain, model, effort, access, instructions, name, timezone, or what it may do without asking)",
+  routine: 'the routine (its instruction, schedule, webhook, skill, model, effort, session or time limit)',
+  connectors: 'its connectors (which ones it has, or their setup, sign-in or on and off)',
+  skills: 'its skills',
+  browser: 'its browser or the sites it may read',
+} as const;
+export type Part = keyof typeof PARTS;
+export type Parts = Record<Part, string>;
+
+const KEEP_TESTS = 5;
+
+export interface GateDeps {
+  store: Store;
+  connectors: Pick<Connectors, 'revision'>;
+  skills: Pick<Skills, 'list'>;
+  browser: { enabled(botId: string): boolean; sites(botId: string): string[] } | null;
+}
+
+export class StarterGate {
+  #d: GateDeps;
+  constructor(deps: GateDeps) {
+    this.#d = deps;
+  }
+
+  /** A keyed hash: opaque to anyone without the server's key, so it may reach a client. */
+  mac(v: unknown): string {
+    return createHmac('sha256', this.#d.store.starterSecret()).update(JSON.stringify(v)).digest('hex').slice(0, 32);
+  }
+
+  /** What connector `id` is now (Connectors.revision), as a keyed hash; one that is gone has its own. */
+  connectorRevision(id: string): string {
+    return this.mac({ id, revision: this.#d.connectors.revision(id) });
+  }
+
+  /** What a turn of `routine` on `bot` runs on, from these very records (not read again). */
+  parts(bot: BotRecord, routine: Routine): Parts {
+    const { store, skills, browser } = this.#d;
+    const boton = {
+      id: bot.id,
+      name: bot.name,
+      title: bot.title,
+      instructions: bot.instructions,
+      provider: bot.provider,
+      model: bot.model,
+      effort: bot.effort,
+      access: bot.access,
+      timezone: bot.timezone,
+      skills: bot.skills,
+      alwaysAllow: bot.alwaysAllow,
+      askFirst: bot.askFirst,
+      owner: store.getSettings().ownerName,
+    };
+    const hook = routine.webhook;
+    const r = {
+      id: routine.id,
+      name: routine.name,
+      instruction: routine.instruction,
+      schedule: routine.schedule,
+      timezone: routine.timezone,
+      webhook: hook ? { source: hook.source, filter: hook.filter, secret: hook.hasSecret, callback: hook.callbackUrl } : null,
+      webhookWorkspace: routine.webhookWorkspace,
+      notify: routine.notify,
+      skill: routine.skill,
+      model: routine.model,
+      effort: routine.effort,
+      session: routine.session,
+      timeLimitMs: routine.timeLimitMs,
+    };
+    const wanted = new Set([...(bot.skills ?? skills.list().map((s) => s.name)), ...(routine.skill ? [routine.skill] : [])]);
+    const skillParts = skills
+      .list()
+      .filter((s) => wanted.has(s.name))
+      .map((s) => [s.name, s.updatedAt, s.version, s.disabled, s.pending, s.updatedBy]);
+    return {
+      boton: this.mac({ boton }),
+      routine: this.mac({ r }),
+      connectors: this.mac({ connectors: bot.connections.map((id) => [id, this.connectorRevision(id)]) }),
+      skills: this.mac({ skills: skillParts, missing: [...wanted].filter((n) => !skillParts.some(([x]) => x === n)).sort() }),
+      browser: this.mac({ browser: browser ? { on: browser.enabled(bot.id), sites: browser.sites(bot.id) } : null }),
+    };
+  }
+
+  /** The parts routine `id` would run on now. */
+  current(id: string): Parts {
+    const routine = this.#d.store.getRoutine(id);
+    return this.parts(this.#d.store.getBot(routine.botId), routine);
+  }
+
+  /**
+   * The engine, as a test run's turn starts: what it runs on. `before` was taken before the turn waited on its
+   * connectors and `after` when it stopped waiting; if they differ, something changed while it was set up, and the run
+   * can't count for turning the routine on.
+   */
+  noteTest(run: Pick<RoutineRun, 'id' | 'routineId' | 'botId' | 'trigger'>, before: Parts, after: Parts): void {
+    if (run.trigger !== 'test') return;
+    const { store } = this.#d;
+    const rec = store.starterRecord(run.botId);
+    if (!rec?.pending.includes(run.routineId)) return;
+    const same = (Object.keys(PARTS) as Part[]).every((k) => before[k] === after[k]);
+    const tests = [{ runId: run.id, routineId: run.routineId, at: nowIso(), parts: same ? after : null }, ...rec.tests.filter((t) => t.runId !== run.id)];
+    const kept = tests.filter((t, i) => tests.slice(0, i).filter((x) => x.routineId === t.routineId).length < KEEP_TESTS);
+    store.saveStarterRecord(run.botId, { ...rec, tests: kept });
+  }
+
+  /** Whether routine `id` of a starter can be turned on without an override now, and why. */
+  verdict(id: string, rec: StarterRecord | null = null): StarterRoutineGate {
+    const { store } = this.#d;
+    const routine = store.getRoutine(id);
+    const record = rec ?? store.starterRecord(routine.botId);
+    const pending = !!record?.pending.includes(id);
+    const out = (tested: boolean, testing: boolean, runId: string | null, text: string): StarterRoutineGate => ({ routineId: id, pending, tested, testing, runId, text });
+    if (!pending) return out(false, false, null, routine.enabled ? 'Turned on by you: an ordinary routine now.' : 'Turned on by you before: an ordinary routine now.');
+    const test = store.listRuns(id).find((x) => x.trigger === 'test');
+    if (!test) return out(false, false, null, 'Not tested yet: run a test, read its reply, then turn it on.');
+    if (test.status === 'queued' || test.status === 'running') return out(false, true, test.id, `A test run is ${test.status}: wait for it to end.`);
+    const when = (test.finishedAt ?? test.startedAt).replace('T', ' ').slice(0, 16);
+    if (test.status !== 'succeeded') return out(false, false, test.id, `The latest test run ${test.status === 'failed' ? 'failed' : 'was skipped'} at ${when} UTC: fix what it says, then test again.`);
+    const noted = record!.tests.find((t) => t.runId === test.id);
+    if (!noted) return out(false, false, test.id, `The latest test run (${when} UTC) ran before this server noted what it ran on: test again.`);
+    if (!noted.parts) return out(false, false, test.id, `Its settings changed while the latest test run (${when} UTC) was being set up: test again.`);
+    const now = this.current(id);
+    const changed = (Object.keys(PARTS) as Part[]).filter((k) => noted.parts![k] !== now[k]);
+    if (changed.length) return out(false, false, test.id, `Changed since the latest test run (${when} UTC): ${changed.map((k) => PARTS[k]).join('; ')}. Test again.`);
+    return out(true, false, test.id, `The latest test run (${when} UTC) finished without an error on its current settings. That doesn't show its output was right: read its reply.`);
+  }
+
+  /**
+   * The owner turns a starter's routine on (the route is theirs alone). Refused while a test run is under way, and
+   * without `override` unless verdict() says tested; all in one synchronous step with the write.
+   */
+  activate(id: string, override: boolean): { routine: Routine; gate: StarterRoutineGate } {
+    const { store } = this.#d;
+    return store.atomically(() => {
+      const routine = store.getRoutine(id);
+      const rec = store.starterRecord(routine.botId);
+      if (!rec?.pending.includes(id)) throw new HttpError(400, `“${routine.name}” is not a starter's routine waiting to be turned on: turn it on as any other routine`);
+      const gate = this.verdict(id, rec);
+      if (gate.testing) throw new HttpError(409, gate.text);
+      if (!gate.tested && !override) throw new HttpError(409, `${gate.text} Or turn it on without a passing test run (override).`);
+      const on = store.updateRoutine(id, { enabled: true }, { starterActivation: true });
+      store.saveStarterRecord(routine.botId, { ...rec, pending: rec.pending.filter((x) => x !== id), tests: rec.tests.filter((t) => t.routineId !== id) });
+      return { routine: on, gate };
+    });
+  }
+}