@chloejs/core 0.2.0

package/serve/tokens.ts

@@ -0,0 +1,132 @@
+// Tokens for other systems, made and revoked from the runtime site.
+//
+// A token is not a second password. It opens the read side of the API and the
+// agents that bind an api channel, and nothing else: it cannot make or revoke
+// tokens, cannot write a file, and cannot reach an agent that has not opted in.
+// The account session is the one that can do everything, and it is only ever
+// held by a browser somebody signed in on.
+//
+// The token itself is shown once, when it is made, and never stored. What is
+// kept is its sha256, so this file leaking is not the same as the tokens
+// leaking. Losing one means revoking it and making another.
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+
+import { STATE } from "#chloe/core/paths.ts";
+
+/** Beside the account and the run history, mode 600. Not in source control. */
+const FILE = `${STATE}/tokens.json`;
+
+/** Long enough that guessing is not a strategy. */
+const BYTES = 32;
+
+/** So a token is recognisable in a log or a config file as something to rotate. */
+const PREFIX = "chloe_";
+
+export interface Token {
+  id: string;
+  /** What it is for, so revoking the right one does not need guesswork. */
+  name: string;
+  /** sha256 of the token, base64url. The token itself was never written down. */
+  hash: string;
+  created: string;
+  lastUsed?: string;
+  revoked?: string;
+}
+
+let held: Token[] | undefined;
+
+function read(): Token[] {
+  if (held) return held;
+  try {
+    held = JSON.parse(readFileSync(FILE, "utf8")) as Token[];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    held = [];
+  }
+  return held;
+}
+
+function write(tokens: Token[]): void {
+  mkdirSync(STATE, { recursive: true });
+  writeFileSync(FILE, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+  chmodSync(FILE, 0o600);
+  held = tokens;
+}
+
+/** Every token, revoked ones included, newest first. Never the secrets: there are none to give. */
+export function tokens(): Token[] {
+  return [...read()].sort((a, b) => b.created.localeCompare(a.created));
+}
+
+/**
+ * A new token. The returned `secret` is the only time it exists in one piece,
+ * so whatever asked for it has to hand it over now or make another.
+ */
+export function makeToken(name: string): { secret: string; token: Token } {
+  const called = name.trim();
+  if (!called) throw new Error("Give the token a name, so you know what you are revoking later.");
+  const secret = PREFIX + crypto.randomBytes(BYTES).toString("base64url");
+  const token: Token = {
+    id: crypto.randomBytes(8).toString("hex"),
+    name: called,
+    hash: digest(secret),
+    created: new Date().toISOString(),
+  };
+  write([...read(), token]);
+  return { secret, token };
+}
+
+/**
+ * Stops a token working, now. The record stays so the list can show what was
+ * revoked and when: a token that vanishes leaves nobody able to answer "was
+ * that one ever real".
+ */
+export function revokeToken(id: string): Token {
+  const all = read();
+  const found = all.find((one) => one.id === id);
+  if (!found) throw new Error("No token with that id.");
+  if (!found.revoked) {
+    found.revoked = new Date().toISOString();
+    write(all);
+  }
+  return found;
+}
+
+/**
+ * The token this value is, or null. Comparing the hashes rather than the
+ * values means a wrong guess never gets to see how much of it was right.
+ */
+export function checkToken(value: string): Token | null {
+  if (!value.startsWith(PREFIX)) return null;
+  const want = digest(value);
+  const found = read().find((one) => !one.revoked && same(one.hash, want));
+  if (found) touch(found);
+  return found ?? null;
+}
+
+/**
+ * When it was last used, to the minute. To the minute because every call would
+ * otherwise rewrite this file, and the answer nobody needs is the second.
+ */
+function touch(token: Token): void {
+  const now = new Date().toISOString();
+  if (token.lastUsed && now.slice(0, 16) === token.lastUsed.slice(0, 16)) return;
+  token.lastUsed = now;
+  write(read());
+}
+
+function digest(value: string): string {
+  return crypto.createHash("sha256").update(value).digest("base64url");
+}
+
+function same(a: string, b: string): boolean {
+  const one = Buffer.from(a), two = Buffer.from(b);
+  if (one.length !== two.length) return false;
+  return crypto.timingSafeEqual(one, two);
+}
+
+/** Forgets what was read, so a test can write the file and be believed. */
+export function forgetTokens(): void {
+  held = undefined;
+}

package/server.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// The server.
+//
+// It loads every agent, starts the clock, opens one port, and watches the tree
+// so an edit is live without a restart. It names no agent: chloe.config.ts
+// lists them, so adding one is adding it to that list.
+//
+// If this process is not running, nothing fires.
+import { existsSync, readdirSync, watch, type FSWatcher } from "node:fs";
+
+import { ROOT } from "#chloe/core/paths.ts";
+import { closeCutOff, trim } from "#chloe/core/db.ts";
+import { loadAll, type Agent, type Running } from "#chloe/load/load.ts";
+import { via } from "#chloe/model/model.ts";
+import { HOST, PORT, serve } from "#chloe/serve/http.ts";
+import { startClock } from "#chloe/core/clock.ts";
+
+// Credentials a channel reads from the environment can be kept in .env beside
+// the repo, which is not in source control.
+if (existsSync(`${ROOT}/.env`)) process.loadEnvFile(`${ROOT}/.env`);
+
+let agents: Map<string, Agent> = await loadAll();
+trim();
+const cutOff = closeCutOff();
+if (cutOff) console.log(`closed ${cutOff} run${cutOff === 1 ? "" : "s"} the last stop cut off`);
+
+const clock = startClock(() => agents);
+
+// Every way in that is not the API: the channels each agent names. A channel
+// keeps running across a reload unless a file in that agent's channels/
+// folder changed, because restarting one drops whatever it was halfway
+// through reading.
+const running = new Map<string, Running>();
+
+function startChannels(changed: Set<string> = new Set()): void {
+  const wanted = new Set<string>();
+  for (const agent of agents.values()) {
+    for (const one of agent.channels) {
+      const key = `${agent.name}/${one.name}`;
+      wanted.add(key);
+      if (running.has(key) && !changed.has(agent.name)) continue;
+      running.get(key)?.stop();
+      running.set(key, one.start(() => agents.get(agent.name)));
+    }
+  }
+  for (const [key, one] of running) {
+    if (!wanted.has(key)) {
+      one.stop();
+      running.delete(key);
+    }
+  }
+}
+startChannels();
+
+serve({
+  host: HOST,
+  port: PORT,
+  agents: () => agents,
+  clock,
+  channels: () => [...running.values()].flatMap((one) => one.routes ?? []),
+});
+
+console.log(`agents: ${[...agents.keys()].join(", ")} on http://${HOST}:${PORT}`);
+console.log(`models: ${via() === "claude" ? "the claude cli, on a subscription" : "the gateway, on a key"}`);
+for (const agent of agents.values()) {
+  for (const job of agent.jobs) {
+    console.log(
+      `  ${agent.name}/${job.id}: ${job.cron ? `${job.cron} ${job.timezone}` : "when started"}` +
+        (job.model ? ` on ${job.model}` : ""),
+    );
+  }
+}
+
+let pending: NodeJS.Timeout | undefined;
+const changedChannels = new Set<string>();
+
+function changed(path: string): void {
+  for (const agent of agents.values()) {
+    if (path.startsWith(`${agent.folder}/channels/`)) changedChannels.add(agent.name);
+  }
+  clearTimeout(pending);
+  pending = setTimeout(reload, 500);
+}
+
+// One at a time. Two at once could finish in the wrong order, and the older
+// read of the files would be the one that stuck.
+let reloading: Promise<void> | undefined;
+let again = false;
+
+async function reload(): Promise<void> {
+  if (reloading) {
+    again = true;
+    return;
+  }
+  reloading = (async () => {
+    do {
+      again = false;
+      try {
+        agents = await loadAll();
+        watchFolders();
+        startChannels(changedChannels);
+        changedChannels.clear();
+        console.log(`reloaded: ${[...agents.keys()].join(", ")}`);
+      } catch (error) {
+        console.error(
+          "reload failed, keeping the agents that were already loaded:",
+          error instanceof Error ? error.message : error,
+        );
+      }
+    } while (again);
+  })();
+  await reloading;
+  reloading = undefined;
+}
+
+/**
+ * Reload when chloe.config.ts or anything in an agent's folder changes.
+ *
+ * Every folder is watched on its own, not recursively. Node's recursive watch
+ * on Linux keeps a watch per file, and a file replaced rather than edited in
+ * place (as git and many editors save) is never heard from again. A folder's
+ * own watch sees every change inside it, however it was written.
+ *
+ * Debounced, because an editor saving one file fires several events, and a
+ * reload halfway through someone writing a file would load a broken one. A
+ * reload that throws keeps the agents that were already working, so a typo in
+ * one agent does not take the others down.
+ */
+const watching = new Map<string, FSWatcher>();
+const SKIP = new Set(["node_modules", ".git", "__pycache__"]);
+
+function foldersIn(folder: string): string[] {
+  const found = [folder];
+  for (const entry of readdirSync(folder, { withFileTypes: true })) {
+    if (entry.isDirectory() && !SKIP.has(entry.name)) found.push(...foldersIn(`${folder}/${entry.name}`));
+  }
+  return found;
+}
+
+function watchFolders(): void {
+  const wanted = new Set([ROOT, ...[...agents.values()].flatMap((one) => foldersIn(one.folder))]);
+  for (const [folder, watcher] of watching) {
+    if (!wanted.has(folder)) {
+      watcher.close();
+      watching.delete(folder);
+    }
+  }
+  for (const folder of wanted) {
+    if (watching.has(folder)) continue;
+    const top = folder === ROOT;
+    const watcher = watch(folder, (_event, file) => {
+      if (file && (!top || file === "chloe.config.ts")) changed(`${folder}/${file}`);
+    });
+    // A folder that is deleted ends its watch with an error, which would otherwise stop the service.
+    watcher.on("error", () => {
+      watcher.close();
+      watching.delete(folder);
+      changed(folder);
+    });
+    watching.set(folder, watcher);
+  }
+}
+watchFolders();
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, () => {
+    clock.stop();
+    process.exit(0);
+  });
+}

package/timer/cron.ts

@@ -0,0 +1,92 @@
+// Five fields, each a `*`, a number, a list, a range or a step like `*/15`.
+// Sunday is 0. Day of month and day of week are both matched, unlike cron's
+// rule that naming both means either: no job here names both.
+
+/** A cron line as the five sets of numbers it means. */
+export interface Cron {
+  minute: number[];
+  hour: number[];
+  dayOfMonth: number[];
+  month: number[];
+  dayOfWeek: number[];
+}
+
+const RANGES: [keyof Cron, number, number][] = [
+  ["minute", 0, 59],
+  ["hour", 0, 23],
+  ["dayOfMonth", 1, 31],
+  ["month", 1, 12],
+  ["dayOfWeek", 0, 6],
+];
+
+/** A cron line as numbers, or a throw saying what it could not read. */
+export function parse(line: string): Cron {
+  const fields = line.trim().split(/\s+/);
+  if (fields.length !== 5) {
+    throw new Error(`A cron line needs five fields, got ${fields.length}: ${JSON.stringify(line)}`);
+  }
+  const cron = {} as Cron;
+  RANGES.forEach(([name, low, high], i) => {
+    cron[name] = field(fields[i], low, high, name);
+  });
+  return cron;
+}
+
+function field(text: string, low: number, high: number, name: string): number[] {
+  const values = new Set<number>();
+  for (const part of text.split(",")) {
+    const [spec, stepText] = part.split("/");
+    const step = stepText ? Number(stepText) : 1;
+    if (!Number.isInteger(step) || step < 1) throw new Error(`Bad step in ${name}: ${part}`);
+
+    let from = low;
+    let to = high;
+    if (spec !== "*") {
+      const bounds = spec.split("-").map(Number);
+      if (bounds.some((n) => !Number.isInteger(n))) throw new Error(`Bad ${name}: ${part}`);
+      from = bounds[0];
+      to = bounds.length > 1 ? bounds[1] : stepText ? high : bounds[0];
+    }
+    if (from < low || to > high || from > to) throw new Error(`${name} out of range (${low}-${high}): ${part}`);
+    for (let n = from; n <= to; n += step) values.add(n);
+  }
+  return [...values].sort((a, b) => a - b);
+}
+
+/** Whether a cron line is due at that moment, in that timezone. */
+export function due(cron: Cron, at: Date, timezone = "UTC"): boolean {
+  const { minute, hour, dayOfMonth, month, dayOfWeek } = inZone(at, timezone);
+  return (
+    cron.minute.includes(minute) &&
+    cron.hour.includes(hour) &&
+    cron.dayOfMonth.includes(dayOfMonth) &&
+    cron.month.includes(month) &&
+    cron.dayOfWeek.includes(dayOfWeek)
+  );
+}
+
+// Intl is the only thing here that knows when New York changed its clocks. An
+// offset worked out by hand is wrong twice a year.
+function inZone(at: Date, timezone: string) {
+  const parts = new Intl.DateTimeFormat("en-GB", {
+    timeZone: timezone,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    weekday: "short",
+  }).formatToParts(at);
+
+  const get = (type: string) => parts.find((p) => p.type === type)?.value ?? "";
+  const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+  return {
+    minute: Number(get("minute")),
+    // Some locales write midnight as 24.
+    hour: Number(get("hour")) % 24,
+    dayOfMonth: Number(get("day")),
+    month: Number(get("month")),
+    dayOfWeek: days.indexOf(get("weekday")),
+  };
+}

package/timer/every.ts

@@ -0,0 +1,153 @@
+// When a job runs, written the way it is said, and turned into a cron line.
+//
+//   every(15).minutes              "*/15 * * * *"
+//   every(4).hours                 "0 */4 * * *"
+//   every.hour.at(30)              "30 * * * *"   (at(0) is on the hour)
+//   every.day.at("07:00")          "0 7 * * *"
+//   every.day.at("10:45", "22:45") "45 10,22 * * *"
+//   every.weekday.at("9:30")       "30 9 * * 1-5"
+//   every.monday.at("9:00")        "0 9 * * 1"
+//   every.month.on(1).at("09:00")  "0 9 1 * *"
+//
+// What comes out is an ordinary cron line, so the loader, the clock and the
+// page read it like any other. Anything a cron line cannot say, or would say
+// differently from how it reads here, is refused with the reason rather than
+// rounded: every(7).minutes would run at :56 and again at :00, so it is not
+// "every 7 minutes", and it is not written.
+//
+// describe() is the other direction, for the page: a line this file could have
+// written comes back as words, and anything else is left as the cron line.
+
+const DAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"] as const;
+
+/** Times of day, "HH:MM" on a 24 hour clock. Several must share the minute, because one cron line has only one. */
+interface OnDays {
+  at(...times: string[]): string;
+}
+
+/**
+ * `every(15).minutes` and `every(4).hours`, as a cron line. A count that does
+ * not divide the hour or the day evenly is refused with the reason.
+ */
+export function every(count: number): { readonly minutes: string; readonly hours: string } {
+  return {
+    get minutes() {
+      evenly(count, 60, "minutes");
+      return `*/${count} * * * *`;
+    },
+    get hours() {
+      evenly(count, 24, "hours");
+      return `0 */${count} * * *`;
+    },
+  };
+}
+
+every.minute = "* * * * *";
+every.hour = {
+  /** Minutes past the hour: every.hour.at(0) is on the hour. */
+  at(minute: number): string {
+    if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+      throw new Error(`every.hour.at(${minute}): the minute past the hour is a whole number from 0 to 59.`);
+    }
+    return `${minute} * * * *`;
+  },
+};
+every.day = onDays("*", "every.day");
+every.weekday = onDays("1-5", "every.weekday");
+every.weekend = onDays("0,6", "every.weekend");
+every.sunday = onDays("0", "every.sunday");
+every.monday = onDays("1", "every.monday");
+every.tuesday = onDays("2", "every.tuesday");
+every.wednesday = onDays("3", "every.wednesday");
+every.thursday = onDays("4", "every.thursday");
+every.friday = onDays("5", "every.friday");
+every.saturday = onDays("6", "every.saturday");
+every.month = {
+  on(day: number): OnDays {
+    // 29 and later are left out on purpose: a job on the 31st would skip
+    // every short month without saying so.
+    if (!Number.isInteger(day) || day < 1 || day > 28) {
+      throw new Error(`every.month.on(${day}): the day is 1 to 28, so it happens in every month.`);
+    }
+    return onDays("*", "every.month", String(day));
+  },
+};
+
+function onDays(days: string, where: string, dayOfMonth = "*"): OnDays {
+  return {
+    at(...list) {
+      const { minute, hours } = times(list, where);
+      return `${minute} ${hours.join(",")} ${dayOfMonth} * ${days}`;
+    },
+  };
+}
+
+function times(list: string[], where: string): { minute: number; hours: number[] } {
+  if (list.length === 0) throw new Error(`${where}.at() needs a time, like "07:00".`);
+  const read = list.map((time) => {
+    const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+    const hour = Number(match?.[1]);
+    const minute = Number(match?.[2]);
+    if (!match || hour > 23 || minute > 59) {
+      throw new Error(`${JSON.stringify(time)} is not a time. Write it on a 24 hour clock, like "07:00" or "22:45".`);
+    }
+    return { hour, minute };
+  });
+  if (new Set(read.map((one) => one.minute)).size > 1) {
+    throw new Error(`${list.join(", ")} do not share a minute, and one cron line has only one. Make them two jobs.`);
+  }
+  return { minute: read[0].minute, hours: [...new Set(read.map((one) => one.hour))].sort((a, b) => a - b) };
+}
+
+/** Only a count that divides the hour or the day, so the gap is the same every time. */
+function evenly(count: number, of: number, unit: string): void {
+  if (Number.isInteger(count) && count > 1 && count < of && of % count === 0) return;
+  const fits = Array.from({ length: of - 2 }, (_, i) => i + 2).filter((n) => of % n === 0);
+  const one = unit === "minutes" ? "every.minute" : "every.hour.at(0)";
+  throw new Error(
+    count === 1
+      ? `every(1).${unit} is ${one}.`
+      : `every(${count}).${unit} does not divide ${unit === "minutes" ? "an hour" : "a day"} evenly, ` +
+        `so the gaps would not all be the same. It can be ${fits.join(", ")}.`,
+  );
+}
+
+/** A cron line in words, when it is one this file could have written. */
+export function describe(cron: string, timezone = "UTC"): string | undefined {
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = cron.trim().split(/\s+/);
+  if (month !== "*") return undefined;
+  const zone = timezone === "UTC" ? "UTC" : timezone.split("/").pop()!.replace(/_/g, " ");
+
+  if (dayOfMonth === "*" && dayOfWeek === "*") {
+    if (cron.trim() === "* * * * *") return "every minute";
+    const minutes = /^\*\/(\d+)$/.exec(minute);
+    if (minutes && hour === "*" && minutes[1] !== "1") return `every ${minutes[1]} minutes`;
+    const hours = /^\*\/(\d+)$/.exec(hour);
+    if (hours && minute === "0" && hours[1] !== "1") return `every ${hours[1]} hours`;
+    if (/^\d+$/.test(minute) && hour === "*") return minute === "0" ? "every hour" : `every hour at :${pad(minute)}`;
+  }
+
+  if (!/^\d+$/.test(minute) || !/^\d+(,\d+)*$/.test(hour)) return undefined;
+  const at = hour
+    .split(",")
+    .map((h) => `${pad(h)}:${pad(minute)}`)
+    .join(" and ");
+
+  const days =
+    dayOfWeek === "*" ? "every day" :
+    dayOfWeek === "1-5" ? "weekdays" :
+    dayOfWeek === "0,6" ? "weekends" :
+    /^[0-6]$/.test(dayOfWeek) ? `${DAYS[Number(dayOfWeek)]}s` :
+    undefined;
+  if (!days) return undefined;
+  if (dayOfMonth === "*") return `${days} at ${at} ${zone}`;
+  if (dayOfWeek === "*" && /^\d+$/.test(dayOfMonth)) return `on the ${nth(Number(dayOfMonth))} of every month at ${at} ${zone}`;
+  return undefined;
+}
+
+const pad = (n: string) => n.padStart(2, "0");
+
+function nth(n: number): string {
+  const end = n % 10 === 1 && n !== 11 ? "st" : n % 10 === 2 && n !== 12 ? "nd" : n % 10 === 3 && n !== 13 ? "rd" : "th";
+  return `${n}${end}`;
+}

package/timer/index.ts

@@ -0,0 +1,4 @@
+// Cron lines, on their own. This folder imports nothing else in chloe, so it
+// can be used without the rest: `import { every, due, parse } from "@chloejs/core/timer"`.
+export { due, parse, type Cron } from "./cron.ts";
+export { describe, every } from "./every.ts";