@chloejs/core 0.2.0

package/core/markdown.ts

@@ -0,0 +1,95 @@
+// Reading the markdown that agents are written in and answer in.
+//
+// A job or a skill is a markdown file that can open with a block of
+// settings between two `---` lines (`cron:`, `name:`), known elsewhere as
+// frontmatter. settingsAndBody() splits one into those settings and the words
+// under them. prompt() points at such a file from code, and readPrompt()
+// reads its words. oneLineSummary() does the other job: it turns a reply
+// written in markdown into one plain line for the overview.
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export interface MarkdownFile {
+  /** What the block at the top says, `cron: "0 23 * * *"` read as { cron: "0 23 * * *" }. */
+  settings: Record<string, string>;
+  /** Everything under that block: the words themselves. */
+  body: string;
+}
+
+// Not YAML on purpose: keys, one-line values, and `#` comments, nothing else.
+export function settingsAndBody(text: string): MarkdownFile {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { settings: {}, body: text.trim() };
+
+  const settings: Record<string, string> = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const at = trimmed.indexOf(":");
+    if (at === -1) continue;
+    settings[trimmed.slice(0, at).trim()] = unquote(trimmed.slice(at + 1).trim());
+  }
+  return { settings, body: match[2].trim() };
+}
+
+function unquote(value: string): string {
+  const quoted = value.match(/^"(.*)"$/) ?? value.match(/^'(.*)'$/);
+  return quoted ? quoted[1] : value;
+}
+
+// Words kept in a markdown file, pointed at from code: an agent's instructions
+// or a job's prompt. The path is inside the agent's folder, "instructions.md"
+// or "jobs/morning-run.md", whichever file names it.
+
+/** Words in a file, read when they are needed rather than as the agent loads. */
+export interface Prompt {
+  file: string;
+}
+
+/**
+ * Declares words in a markdown file inside the agent's folder: its
+ * instructions, or a job's prompt.
+ */
+export function prompt(file: string): Prompt {
+  return { file };
+}
+
+/** Whether a value is a declared prompt rather than words written inline. */
+export function isPrompt(value: unknown): value is Prompt {
+  return typeof value === "object" && value !== null && typeof (value as Prompt).file === "string";
+}
+
+/**
+ * The words themselves, from a plain string or from the file a marker names.
+ * `where` is what to call the declaring file when something is wrong.
+ */
+export async function readPrompt(
+  from: string | Prompt | undefined,
+  options: { dir: string; where: string },
+): Promise<string> {
+  if (typeof from === "string") return from.trim();
+  if (!isPrompt(from)) throw new Error(`${options.where} has no words. Give it a string or prompt("./name.md").`);
+
+  const text = await readFile(resolve(options.dir, from.file), "utf8").catch(() => {
+    throw new Error(`${options.where} points at ${JSON.stringify(from.file)}, which is not there.`);
+  });
+  // Only the body, so a file that kept a settings block at the top does not
+  // read it out to a model as if it were instructions.
+  const words = settingsAndBody(text).body;
+  if (!words.trim()) throw new Error(`${options.where} points at ${JSON.stringify(from.file)}, which is empty.`);
+  return words;
+}
+
+/**
+ * The start of a reply as one plain line: list marks, emphasis and headings
+ * gone, lines joined, cut at `max`. It is how the reply begins, not what it
+ * means: nothing here reads it.
+ */
+export function oneLineSummary(text: string, max = 200): string {
+  const line = text
+    .split(/\r?\n/)
+    .map((one) => one.replace(/[*`#>]|__/g, "").replace(/^\s*(-|\d+\.)\s+/, "").trim())
+    .filter(Boolean)
+    .join(" ");
+  return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+}

package/core/notes.ts

@@ -0,0 +1,44 @@
+// A small JSON file one agent writes and reads back next time.
+//
+// The shape is a zod schema ending in `.catch(...)`, so a missing file and an
+// unreadable one both come back as the default rather than stopping the run.
+// That forgiveness is why the write has to be atomic: two jobs can want the
+// same note at the same moment, one writing and one reading, and a reader that
+// caught half a file would not fail. It would quietly get the default and
+// report on an empty world.
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { z } from "zod";
+
+import { STATE } from "./paths.ts";
+
+/** One JSON file an agent keeps, read and written against a schema. */
+export interface Note<T> {
+  path: string;
+  read(): Promise<T>;
+  write(value: T): Promise<T>;
+}
+
+/**
+ * A note by name, in that agent's own state folder. A shape with a `catch`
+ * makes a note that is not there read as its default.
+ */
+export function note<T>(agent: string, name: string, shape: z.ZodType<T>): Note<T> {
+  const path = join(STATE, agent, `${name}.json`);
+  return {
+    path,
+    async read() {
+      return shape.parse(await readFile(path, "utf8").then(JSON.parse).catch(() => undefined));
+    },
+    async write(value) {
+      await mkdir(dirname(path), { recursive: true });
+      // Beside the note, so the rename stays on one filesystem and is atomic:
+      // a reader sees the whole of the old file or the whole of the new one.
+      const part = `${path}.${process.pid}.part`;
+      await writeFile(part, JSON.stringify(value, null, 2));
+      await rename(part, path);
+      return value;
+    },
+  };
+}

package/core/paths.ts

@@ -0,0 +1,29 @@
+// The paths the runtime itself needs. Nothing here names a person, a home
+// directory or a machine: the repo finds itself, and everything else is either
+// relative to that or said in settings.local.json, which is not in source
+// control. Paths that belong to one agent live in that agent's folder.
+import { ROOT } from "./root.ts";
+import { setting, settings } from "./settings.ts";
+
+export { ROOT };
+
+// Filled by the loader from what each agent declared, before any tool is bound.
+let folders = new Map<string, string>();
+
+export function setAgentDirs(declared: Map<string, string>): void {
+  folders = declared;
+}
+
+/** One agent's own folder: its skills, scripts, evals and prompts. */
+export function agentDir(name: string): string {
+  const folder = folders.get(name);
+  if (!folder) throw new Error(`No agent called ${JSON.stringify(name)} has been loaded.`);
+  return folder;
+}
+
+/**
+ * Everything the agents keep: their own folders (journals, metrics, notes) and
+ * the run history. Unset, it is `data/` inside the repo, which git ignores, so
+ * a second clone keeps its own state. `git clean -x` would delete it.
+ */
+export const STATE = setting(settings.state, "AGENTS_STATE") || `${ROOT}/data`;

package/core/root.ts

@@ -0,0 +1,26 @@
+// Where the repo is. Its own file so that paths.ts can read settings: settings
+// needs ROOT to find the two settings files, and would otherwise import the
+// file that imports it.
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/**
+ * The repo root: the folder that holds chloe.config.ts, walking up from the
+ * running process. data/, .env and the settings files are found beside it.
+ */
+function findRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(resolve(dir, "chloe.config.ts"))) return dir;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  throw new Error(`No chloe.config.ts at or above ${process.cwd()}. Start the agents from inside the repo.`);
+}
+
+/**
+ * The folder that holds `chloe.config.ts`, found by walking up from where the
+ * process was started.
+ */
+export const ROOT = findRoot();

package/core/settings.ts

@@ -0,0 +1,124 @@
+// Every setting, and what it is when nobody says.
+//
+// Three files, read in this order, each one winning over the one before:
+//
+//   the schema below     the default, and the documentation
+//   settings.json        in source control: true for everyone who clones this
+//   settings.local.json  not in source control: true for this box only
+//
+// An environment variable beats all three. That is for a one-off run
+// (MODEL_VIA=gateway npm run evals) and for the tests, not for keeping
+// settings in.
+//
+// A value that names a home directory, a machine, a person, or is a
+// credential (a bot token, a chat id) belongs in settings.local.json, so
+// setting chloe up is filling in that one file. Nothing in source control may
+// hold any of them.
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+
+import { ROOT } from "./root.ts";
+
+const schema = z.object({
+  model: z
+    .object({
+      /** "gateway" for HTTP, "claude" for the CLI. Empty picks by what the machine has. */
+      via: z.enum(["gateway", "claude", ""]).default(""),
+      /** Any gateway that speaks the OpenAI chat-completions shape. */
+      gateway: z.string().default("https://ai-gateway.vercel.sh/v1/chat/completions"),
+      /** The gateway's key. Empty means no gateway, so via "" picks the CLI. */
+      key: z.string().default(""),
+      /** Who marks an eval. Cheaper than the agent being marked, on purpose. */
+      judge: z.string().default("anthropic/claude-sonnet-5"),
+    })
+    .prefault({}),
+  app: z
+    .object({
+      /** Where an agent's mail goes. Comma separated for more than one. */
+      send_email_to: z.string().default(""),
+    })
+    .prefault({}),
+  /** Sending mail. */
+  resend: z
+    .object({
+      /** The key an agent's mail is sent with. Without one, nothing is sent. */
+      api_key: z.string().default(""),
+    })
+    .prefault({}),
+  google: z
+    .object({
+      /** The account a mail tool reads from. */
+      account: z.string().default(""),
+      /** Opens the saved login, from when a person signed in to that account. */
+      password: z.string().default(""),
+      /** The Analytics service account's key, handed to scripts as GA_KEY_FILE. */
+      GA_KEY_FILE: z.string().default(""),
+    })
+    .prefault({}),
+  /** Mail sent when somebody signs in from an address this copy has not seen. */
+  alerts: z
+    .object({
+      /** Where it goes. Empty means nothing is sent, and the sign-in is still recorded. */
+      email_to: z.string().default(""),
+      /** The From line, e.g. "Chloe <info@example.com>". */
+      email_from: z.string().default(""),
+    })
+    .prefault({}),
+  /** Everything the agents keep: their folders and the run history. Empty means data/ inside the repo. */
+  state: z.string().default(""),
+  /** Which node the unit runs. Empty means whichever is on the path at install. */
+  node: z.string().default(""),
+});
+
+/** Every setting there is, as the schema defines it. */
+export type Settings = z.infer<typeof schema>;
+
+function read(name: string): unknown {
+  try {
+    return JSON.parse(readFileSync(`${ROOT}/${name}`, "utf8"));
+  } catch (error) {
+    // Missing is normal: the whole file is optional. Malformed is not, because
+    // silently falling back to the defaults is how a box runs for a week on
+    // settings nobody chose.
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error(`${name} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/** One level down, so a file can set model.via without restating model.gateway. */
+function merge(base: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown> {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(over)) {
+    const mine = out[key];
+    out[key] =
+      value && typeof value === "object" && !Array.isArray(value) && mine && typeof mine === "object" && !Array.isArray(mine)
+        ? { ...(mine as object), ...(value as object) }
+        : value;
+  }
+  return out;
+}
+
+/**
+ * The two files merged and checked. Separate from reading them so it can be
+ * tested without a disk, and so the order that wins is one readable line.
+ */
+export function readSettings(tracked: unknown, local: unknown): Settings {
+  const found = schema.safeParse(merge(tracked as Record<string, unknown>, local as Record<string, unknown>));
+  if (!found.success) throw new Error(`settings are not valid:\n${z.prettifyError(found.error)}`);
+  return found.data;
+}
+
+/**
+ * The settings this process started with: the schema's defaults, then
+ * `settings.json`, then `settings.local.json`. One value can still be beaten
+ * by an environment variable, through `setting()`.
+ */
+export const settings: Settings = readSettings(read("settings.json"), read("settings.local.json"));
+
+/**
+ * A setting, with an environment variable winning if there is one. Reading it
+ * here rather than at import time is what lets a test set one.
+ */
+export function setting(value: string, fromEnv: string): string {
+  return process.env[fromEnv] || value;
+}