Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,10 @@ a laptop.
- `src/github.js`: the GitHub Actions webhook check, the fields it keeps, and the pull queue (pure, tested).
- `src/usage.js`: what `/ingest/usage` and `/ingest/limits` accept (`cleanUsage`, `cleanLimits`) and how
`/usage/data` sums usage per Halifax day (pure, tested); the `Usage` Durable Object (SQLite, migration `v2`;
`seat_limits` is created in code) is in `src/worker.js`. Private: never route it to the Hub.
`seat_limits` is created in code) is in `src/worker.js`. Private: never route it to the Hub. Its seats are
the employees in `src/hq-registry.json`, plus polaris, codex and other.
- `scripts/copy-hq-registry.mjs`: writes `src/hq-registry.json` from setkernel/hq `registry/people.csv`
(setkernel-live#96): each employee who isn't removed, handles only (`--check` compares).
- `src/watch.js`: when to post "updates stopped" and "updates resumed" to Buzz (pure, tested).
- `src/buzz.js`: signs and posts a Buzz message as the Worker's own identity (tested).
- `src/evidence.js`: the v4 showcase's publisher (setkernel-live#52), a public pull request's evidence and
Expand Down Expand Up @@ -136,6 +139,8 @@ a laptop.
(set only in `ci.yml`) a failed request fails it; elsewhere, including the deploy's re-gate (no
token), it skips. A repo the page names that isn't on that list fails it.
`evidence.json` is regenerated by `build.mjs --fetch` and goes through `publishEvidence`; never edit it by hand.
- `src/hq-registry.json` is written only by `scripts/copy-hq-registry.mjs`; never edit it by hand, and never
copy more than handles into it (no logins, ids, names or emails: this repo is public).
- vitest stays on 4.1.x for now: with vitest 5.0.4, `@cloudflare/vitest-plugin` 1.4.0 fails every
suite ("no such file or directory, readAll …/.vitest-cache/…").
- In worker tests, read every response body. An unread body keeps the request open, and
Expand Down
11 changes: 8 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,20 +224,25 @@ Hours older than 400 days are deleted on each push.
checks `INGEST_AUD` again. Body (up to 256 KiB): `{ "buckets": [{ "hour": "2026-10-14T15",
"seat": "vega", "model": "claude-opus-5-5", "surface": "vm", "input": 0, "output": 0,
"cache_read": 0, "cache_write": 0, "usd_micros": 0, "requests": 0 }] }`. `hour` is a UTC hour;
seat is one of vega, rigel, lyra, orion, polaris, codex, other; surface one of vm, desktop, cli,
seat is an employee in `src/hq-registry.json` (below), polaris, codex or other; surface one of vm, desktop, cli,
cloud, codex; the counts are whole numbers from 0. One bad bucket makes the whole push 400.
A bucket pushed again replaces the stored one, so a pusher can resend an hour's running totals.
The answer is `{ stored, days }`: what is now stored for the hours pushed, per Halifax day and seat.
- `POST /ingest/limits` (setkernel-live#88) takes each seat's newest 5-hour and weekly limit readings,
behind the same Access app and `INGEST_AUD` check: `{ "vega": { "five_hour": { "utilization": 0.84,
"resets_at": "…", "observed_at": "…" }, "seven_day": { … }, "event": { "status": "rejected",
"rate_limit_type": "five_hour", "resets_at": "…", "received_at": "…" } } }`. The seats are vega, rigel,
lyra, orion and polaris (Codex has no Claude limits); `utilization` is a fraction from 0; times are
"rate_limit_type": "five_hour", "resets_at": "…", "received_at": "…" } } }`. The seats are the
registry copy's employees and polaris (Codex has no Claude limits); `utilization` is a fraction from 0; times are
ISO 8601 with a zone (`resets_at` may be null: unknown); `status` is allowed, allowed_warning or
rejected; any part may be null or left out, and changes nothing then. Other fields are dropped; a bad
seat, value or time makes the whole push 400. The store (`seat_limits`, one row per seat and part)
keeps a part only if it is as new as or newer than the one it has, and answers `{ limits }`: every
seat's as now stored.
- The employees are a copy of setkernel/hq's `registry/people.csv` (setkernel-live#96): each employee
who isn't removed, as the wall gives them a lane, handles only. A person added or removed there
needs no code edit here, only a fresh copy: `node scripts/copy-hq-registry.mjs --hq <hq checkout>`,
then commit `src/hq-registry.json` (`--check` exits 1 when the committed copy differs). Never edit
it by hand.
- `GET /usage/data?month=YYYY-MM` needs a token for its own Access app, checked against
`USAGE_AUD` (the "live usage" Access app, setkernel-cloudflare#119; its tag is in `wrangler.jsonc`).
With no login Access answers 302 to its login page; if `USAGE_AUD` were ever empty the Worker would
Expand Down
66 changes: 66 additions & 0 deletions scripts/copy-hq-registry.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
// Copies who works here from the hq registry (setkernel/hq registry/people.csv) into src/hq-registry.json
// (setkernel-live#96, setkernel/hq#1089), so the usage ingest's seats (src/usage.js) are no hand-written list.
// Handles only: this repo is public, so no logins, ids, names or emails. The same people the wall gives a lane
// (hq observability/wall/server.py's lanes()): each employee who isn't removed, in the file's order.
//
// node scripts/copy-hq-registry.mjs --hq <hq checkout> write the file
// node scripts/copy-hq-registry.mjs --check --hq <hq checkout> exit 1 when the committed file differs
//
// Exit 0: written, or no difference. 1: the registry can't be read or the file differs. 2: bad usage.
import { readFileSync, writeFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

export const OUT = join(dirname(fileURLToPath(import.meta.url)), "..", "src", "hq-registry.json");
const HANDLE = /^[a-z][a-z0-9-]{0,31}$/; // hq registry/naming.md's handle; a row with anything else is left out

// The registry has no quoted fields; a quote is refused rather than half-parsed.
export function parseCsv(text) {
const lines = text.split(/\r?\n/).filter((l) => l.trim() !== "");
if (lines.length === 0) throw new Error("empty csv");
if (text.includes('"')) throw new Error("quoted csv fields are not supported");
const head = lines[0].split(",");
for (const h of ["handle", "kind", "status"]) if (!head.includes(h)) throw new Error(`no ${h} column`);
return lines.slice(1).map((l) => {
const cells = l.split(",");
if (cells.length !== head.length) throw new Error(`row has ${cells.length} fields, header has ${head.length}`);
return Object.fromEntries(head.map((h, i) => [h, cells[i].trim()]));
});
}

// people.csv's text -> the canonical text of src/hq-registry.json.
export function render(peopleCsv) {
const employees = [];
for (const r of parseCsv(peopleCsv)) {
if (r.kind === "employee" && r.status !== "removed" && HANDLE.test(r.handle) && !employees.includes(r.handle)) employees.push(r.handle);
}
return JSON.stringify({ employees }, null, 2) + "\n";
}

function main(argv) {
const i = argv.indexOf("--hq");
const hq = i >= 0 ? argv[i + 1] : undefined;
if (!hq) {
console.error("usage: copy-hq-registry.mjs [--check] --hq <hq checkout>");
return 2;
}
let text;
try {
text = render(readFileSync(join(hq, "registry", "people.csv"), "utf8"));
} catch (e) {
console.error(`copy-hq-registry: ${e.message}`);
return 1;
}
if (argv.includes("--check")) {
let have = null;
try { have = readFileSync(OUT, "utf8"); } catch { /* missing counts as differing */ }
if (have === text) return 0;
console.error("copy-hq-registry: src/hq-registry.json differs from the hq registry");
return 1;
}
writeFileSync(OUT, text);
return 0;
}

// Not import.meta.main: that needs Node 24.2 (scripts/smoke.mjs says the same).
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main(process.argv.slice(2));
8 changes: 8 additions & 0 deletions src/hq-registry.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"employees": [
"vega",
"rigel",
"lyra",
"orion"
]
}
20 changes: 13 additions & 7 deletions src/usage.js
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,13 @@
// Usage Durable Object keeps them apart from the Hub, so no public route can return them. Pure and
// tested (test/usage.test.mjs); the Durable Object is in src/worker.js.
import { homeDay } from "../public/lib/state.js";
import registry from "./hq-registry.json" with { type: "json" };

export const SEATS = ["vega", "rigel", "lyra", "orion", "polaris", "codex", "other"];
// Who may push usage (setkernel-live#96): each employee in the hq registry's copy (written by
// scripts/copy-hq-registry.mjs, never by hand), then the seats that are no one there: polaris (Raghav's
// own sessions), codex and other. A person added to or removed from the registry needs no code edit.
export const usageSeats = (employees) => [...employees, "polaris", "codex", "other"];
export const SEATS = usageSeats(registry.employees);
export const SURFACES = ["vm", "desktop", "cli", "cloud", "codex"];
export const COUNTS = ["input", "output", "cache_read", "cache_write", "usd_micros", "requests"];
export const KEEP_DAYS = 400;
Expand All @@ -23,12 +28,12 @@ export const hourOf = (ms) => new Date(ms).toISOString().slice(0, 13);

// { buckets: [{ hour, seat, model, surface, input, output, cache_read, cache_write, usd_micros,
// requests }] } -> the buckets with only those fields, or null if any of them is not allowed.
export function cleanUsage(body) {
export function cleanUsage(body, seats = SEATS) {
if (!body || typeof body !== "object" || !Array.isArray(body.buckets)) return null;
const out = [];
for (const b of body.buckets) {
if (!b || typeof b !== "object") return null;
if (Number.isNaN(hourMs(b.hour)) || !SEATS.includes(b.seat) || !SURFACES.includes(b.surface)) return null;
if (Number.isNaN(hourMs(b.hour)) || !seats.includes(b.seat) || !SURFACES.includes(b.surface)) return null;
if (typeof b.model !== "string" || !MODEL.test(b.model)) return null;
if (!COUNTS.every((k) => Number.isSafeInteger(b[k]) && b[k] >= 0)) return null;
out.push({ hour: b.hour, seat: b.seat, model: b.model, surface: b.surface, ...Object.fromEntries(COUNTS.map((k) => [k, b[k]])) });
Expand All @@ -39,7 +44,8 @@ export function cleanUsage(body) {
// Each seat's 5-hour and weekly limit windows (setkernel-live#88): the newest reading per seat, pushed
// to POST /ingest/limits and read back as `limits` from GET /usage/data, in the shape
// public/usage/limits.js reads. Codex has no Claude limits, and "other" is no seat, so neither has any.
export const LIMIT_SEATS = SEATS.filter((s) => s !== "codex" && s !== "other");
export const limitSeats = (employees) => usageSeats(employees).filter((s) => s !== "codex" && s !== "other");
export const LIMIT_SEATS = limitSeats(registry.employees);
export const WINDOWS = ["five_hour", "seven_day"];
export const STATUSES = ["allowed", "allowed_warning", "rejected"];
const ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(?:Z|[+-](\d{2}):(\d{2}))$/;
Expand Down Expand Up @@ -72,15 +78,15 @@ function cleanEvent(e) {
return resets_at === undefined || !received_at ? undefined : { status: e.status, rate_limit_type: e.rate_limit_type, resets_at, received_at };
}

// { <seat>: { five_hour, seven_day, event } } -> the same with only LIMIT_SEATS, each window's
// { <seat>: { five_hour, seven_day, event } } -> the same with only the seats given (LIMIT_SEATS), each window's
// utilization (a fraction, 0.84), resets_at and observed_at, and the event's status, rate_limit_type,
// resets_at and received_at, times as toISOString() gives them and a missing part null; or null if any
// seat, window or event is not allowed. Fields it doesn't name are dropped.
export function cleanLimits(body) {
export function cleanLimits(body, seats = LIMIT_SEATS) {
if (!plain(body)) return null;
const out = {};
for (const [seat, s] of Object.entries(body)) {
if (!LIMIT_SEATS.includes(seat) || !plain(s)) return null;
if (!seats.includes(seat) || !plain(s)) return null;
const five_hour = cleanWindow(s.five_hour), seven_day = cleanWindow(s.seven_day), event = cleanEvent(s.event);
if (five_hour === undefined || seven_day === undefined || event === undefined) return null;
out[seat] = { five_hour, seven_day, event };
Expand Down
37 changes: 36 additions & 1 deletion test/usage.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@
import { test } from "node:test";
import assert from "node:assert/strict";
import { COUNTS, SEATS, SURFACES, cleanUsage, hourMs, keepFrom, monthRange, sumByDay } from "../src/usage.js";
import { LIMIT_SEATS, cleanLimits, isoTime } from "../src/usage.js";
import { LIMIT_SEATS, cleanLimits, isoTime, limitSeats, usageSeats } from "../src/usage.js";
import { render } from "../scripts/copy-hq-registry.mjs";
import registry from "../src/hq-registry.json" with { type: "json" };

const bucket = (extra = {}) => ({ hour: "2026-10-14T15", seat: "vega", model: "claude-opus-5-5", surface: "vm", input: 10, output: 20, cache_read: 30, cache_write: 40, usd_micros: 50, requests: 1, ...extra });
const counts = (n) => Object.fromEntries(COUNTS.map((k) => [k, n]));
Expand All @@ -26,6 +28,39 @@ test("cleanUsage refuses the whole push for any bad bucket", () => {
for (const body of [null, [], "x", {}, { buckets: {} }, { buckets: [null] }, { buckets: ["x"] }]) assert.equal(cleanUsage(body), null, JSON.stringify(body));
});

// A scratch registry/people.csv, in hq's columns, with made-up logins and ids.
const people = (...rows) => ["handle,kind,github_login,github_id,status,persona,lane", "boss,owner,boss-login,1,active,no,", ...rows].join("\n") + "\n";
const employee = (handle, status = "active", n = 2) => `${handle},employee,${handle}-login,${n},${status},yes,`;

test("the seats are the registry copy's employees, then polaris, codex and other; anyone else is refused", () => {
assert.deepEqual(Object.keys(registry), ["employees"], "handles only: this repo is public");
assert.ok(registry.employees.length > 0 && registry.employees.every((h) => /^[a-z][a-z0-9-]{0,31}$/.test(h)), JSON.stringify(registry));
assert.deepEqual(SEATS, [...registry.employees, "polaris", "codex", "other"]);
assert.deepEqual(LIMIT_SEATS, [...registry.employees, "polaris"]);
const stranger = registry.employees.join("-").slice(0, 31) + "x"; // a handle the copy doesn't hold, whoever it holds
assert.equal(cleanUsage({ buckets: [bucket({ seat: stranger })] }), null, stranger);
assert.equal(cleanLimits({ [stranger]: {} }), null, stranger);
});

test("a fifth employee row in a scratch registry copy is a seat with no code change; owner and removed rows are not", () => {
const csv = people(employee("vega"), employee("rigel"), employee("lyra"), employee("orion"), employee("vela"), employee("nova", "removed"), employee("pax", "paused"));
const { employees } = JSON.parse(render(csv));
assert.deepEqual(employees, ["vega", "rigel", "lyra", "orion", "vela", "pax"]);
assert.ok(!render(csv).includes("login"), "no logins or ids in the copy");
assert.deepEqual(cleanUsage({ buckets: [bucket({ seat: "vela" })] }, usageSeats(employees)), [bucket({ seat: "vela" })]);
assert.deepEqual(cleanLimits({ vela: {} }, limitSeats(employees)), { vela: { five_hour: null, seven_day: null, event: null } });
for (const s of ["nova", "boss", "Vela"]) {
assert.equal(cleanUsage({ buckets: [bucket({ seat: s })] }, usageSeats(employees)), null, s);
assert.equal(cleanLimits({ [s]: {} }, limitSeats(employees)), null, s);
}
assert.equal(cleanLimits({ codex: {} }, limitSeats(employees)), null);
// A row that isn't a plain handle is left out, and the same handle twice counts once.
assert.deepEqual(JSON.parse(render(people(employee("vega"), employee("Bad Name"), employee("vega")))).employees, ["vega"]);
for (const bad of ["", 'handle,kind,status\n"vega",employee,active\n', "handle,kind,status\nvega,employee\n", "handle,kind\nvega,employee\n"]) {
assert.throws(() => render(bad), JSON.stringify(bad));
}
});

const win = (extra = {}) => ({ utilization: 0.84, resets_at: "2026-11-04T16:10:00.000Z", observed_at: "2026-11-04T14:55:00.000Z", ...extra });
const ev = (extra = {}) => ({ status: "rejected", rate_limit_type: "five_hour", resets_at: "2026-11-04T16:10:00.000Z", received_at: "2026-11-04T14:47:00.000Z", ...extra });
const seat = (extra = {}) => ({ five_hour: win(), seven_day: win({ utilization: 0.52 }), event: ev(), ...extra });
Expand Down
Loading