@chloejs/core 0.2.4 → 0.3.0

package/README.md

@@ -146,7 +146,8 @@ outside one runs again on every resume, so it must not send, write or spend.
 | Tools | A description, a schema and one call. Typed at both ends. |
 | Human approvals | A run parks for days and carries on when somebody answers. |
 | Channels | Telegram and Slack, one file each. A question goes out where the person is. |
-| Memory | Notes an agent keeps, and skills it can rewrite. |
+| Memory | A folder of notes per agent, in one git repository of their own: one commit per run, under the agent's name. |
+| Self-improvement | An agent can rewrite its skills, jobs and instructions if you let it, never its code. Every change can be undone. |
 | Run history | Every step of every run, with its arguments and its answer. |
 | Cost tracking | Per step, per run, per job. |
 | Structured output | Zod on every model and agent answer, retried once. |

package/channels/shared.ts

@@ -24,7 +24,7 @@
 import type { Agent, ChatHistory, Job } from "#chloe/load/load.ts";
 import type { Attachment } from "#chloe/model/model.ts";
 import { remember } from "#chloe/model/memory.ts";
-import { clock, type Fired } from "#chloe/core/clock.ts";
+import { clock, type Fired, ran } from "#chloe/core/clock.ts";
 import { answer, waitingOn, WrongInput } from "#chloe/core/steps.ts";
 import { turn } from "#chloe/core/turn.ts";
 
@@ -177,6 +177,18 @@ function kept(message: Incoming, reply: string): void {
   remember(message.thread, "assistant", reply);
 }
 
+/**
+ * A message that is for a job: start that job and hand back what to say.
+ *
+ * The message becomes the job's input (the text, and who said it and where, so
+ * the job can write back to the same chat), the clock runs it, and the reply is
+ * the job's own words. Three things can come back and each is said plainly: the
+ * job ran, the job was already running, or the job failed.
+ *
+ * It goes through the clock rather than calling the job itself, because the
+ * clock is the one place that knows what is running and will not start a second
+ * run of the same job.
+ */
 async function started(agent: Agent, message: Incoming, job: Job, text: string): Promise<Handled> {
   const input = {
     text,
@@ -189,7 +201,12 @@ async function started(agent: Agent, message: Incoming, job: Job, text: string):
   };
   try {
     const result = await clock()!.fire(agent, job, input, message.channel);
-    if (!result) return { text: `${job.id} is already running. I will not start a second one.`, steps: 0, cost: 0, job: job.id };
+    if (!ran(result)) {
+      const text = result.skipped
+        ? `${job.id} is already running. I will not start a second one.`
+        : `${job.id} failed. ${result.failed ?? "It is in the logs on the box."}`;
+      return { text, steps: 0, cost: 0, job: job.id };
+    }
     const reply = replyOf(result, job);
     kept(message, reply);
     return { text: reply, runId: result.runId, steps: result.steps, cost: result.cost, job: job.id };
@@ -237,6 +254,7 @@ async function chatted(agent: Agent, message: Incoming, rules: Rules, send?: (te
       thread: message.thread || undefined,
       history: rules.chatHistory,
       said,
+      talkingTo: message.from.name,
       model: message.model,
       source: message.channel,
       owner: `${message.channel}:${message.from.id}`,

package/channels/slack.ts

@@ -14,8 +14,9 @@
 // Under Event Subscriptions subscribe the bot to message.im, message.channels,
 // message.groups and message.mpim, and under App Home allow messages from the
 // Messages tab. Install it to the workspace, which makes the bot token
-// ("xoxb-..."). The two tokens are SLACK_BOT_TOKEN and SLACK_APP_TOKEN in
-// .env, or `credentials: { botToken, appToken }`. In a channel, invite the bot
+// ("xoxb-..."). The two tokens are in settings.local.json under the agent's
+// name, as `"agents": { "<name>": { "slack": { "bot_token", "app_token" } } }`,
+// or `credentials: { botToken, appToken }` here. In a channel, invite the bot
 // (/invite @name) before it can read anything there.
 //
 // allowFrom is who may talk to the agent, by Slack member id ("U0123ABCD", in
@@ -38,6 +39,7 @@
 import { ownedBy, reachBy, unreach } from "#chloe/model/ask.ts";
 import type { Agent, Channel, ChatHistory, Running } from "#chloe/load/load.ts";
 import type { Attachment } from "#chloe/model/model.ts";
+import { settings } from "#chloe/core/settings.ts";
 import { receive, type Incoming, type Rules } from "./shared.ts";
 
 const MAX_MESSAGE = 4000; // Slack cuts a message's text at 40000, and advises under 4000.
@@ -50,7 +52,7 @@ export interface SlackOptions {
    * run came in on, and the start of every address on this app, like "slack:U0123ABCD".
    */
   name?: string;
-  /** Instead of SLACK_BOT_TOKEN and SLACK_APP_TOKEN. */
+  /** Instead of the tokens in settings. */
   credentials?: { botToken?: string; appToken?: string };
   /** Slack member ids that may reach the agent. */
   allowFrom?: string[];
@@ -105,14 +107,15 @@ export function slackChannel(options: SlackOptions = {}): Channel {
   return {
     name: options.name ?? "slack",
     chatHistory: options.chatHistory,
+    madeWith: JSON.stringify(options),
     start(agent) {
       const name = agent()?.name ?? "";
-      const token = options.credentials?.botToken || process.env.SLACK_BOT_TOKEN || "";
-      const appToken = options.credentials?.appToken || process.env.SLACK_APP_TOKEN || "";
+      const token = options.credentials?.botToken || settings.agents[name]?.slack.bot_token || "";
+      const appToken = options.credentials?.appToken || settings.agents[name]?.slack.app_token || "";
       if (!token || !appToken) {
         console.error(
           `slack: ${name} has a Slack channel but no ${token ? "app token" : "bot token"}. Make an app at api.slack.com/apps ` +
-            "with Socket Mode on, and put its tokens in .env as SLACK_BOT_TOKEN (xoxb-...) and SLACK_APP_TOKEN (xapp-...). Then restart.",
+            `with Socket Mode on, and put its tokens in settings.local.json as "agents": { "${name}": { "slack": { "bot_token": "xoxb-...", "app_token": "xapp-..." } } }.`,
         );
         return { stop: () => {} };
       }

package/channels/telegram.ts

@@ -4,9 +4,10 @@
 //   import { telegramChannel } from "@chloejs/core/channels";
 //   channels: [telegramChannel({ allowFrom: [111111111] })],
 //
-// The bot's token is TELEGRAM_BOT_TOKEN, or `credentials: { botToken }`. To
-// make a bot, message @BotFather in Telegram, send /newbot, and pick a name
-// and a username. It replies with the token.
+// The bot's token is in settings.local.json under the agent's name, as
+// `"agents": { "<name>": { "telegram": "..." } }`, or `credentials: { botToken }`
+// here. To make a bot, message @BotFather in Telegram, send /newbot, and pick
+// a name and a username. It replies with the token.
 //
 // allowFrom is who may talk to the agent, by Telegram user id, in any chat,
 // including a group made later. Anyone can find a bot and message it, so
@@ -21,8 +22,8 @@
 //              default.
 //   "webhook"  Telegram sends each one to publicUrl + /chloe/v1/<agent>/telegram,
 //              which has to be reachable past the login, and checks
-//              TELEGRAM_WEBHOOK_SECRET_TOKEN (or credentials.webhookSecretToken)
-//              on every call. chloe registers the address itself on start.
+//              credentials.webhookSecretToken, or one made on start, on every
+//              call. chloe registers the address itself on start.
 //
 // What happens to a message once it is read (allowFrom, a job waiting on an
 // answer, /commands, jobs that answer plain messages, groups, the chat) is
@@ -36,9 +37,10 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { type Agent, type Channel, type ChatHistory, type Running } from "#chloe/load/load.ts";
 import { ownedBy, reachBy, unreach } from "#chloe/model/ask.ts";
 import type { Attachment } from "#chloe/model/model.ts";
+import { settings } from "#chloe/core/settings.ts";
 import { commands, receive, type Incoming, type Rules } from "./shared.ts";
 
-const MAX_MESSAGE = 4000; // Telegram rejects anything over 4096.
+const MAX_MESSAGE = 3500; // Telegram rejects anything over 4096, and the tags added below count.
 const WAIT = 50; // Seconds Telegram holds a poll open when there is nothing new.
 
 /**
@@ -53,7 +55,7 @@ export interface TelegramOptions {
   name?: string;
   /** For spotting a mention in a group. Asked of Telegram when left out. */
   botUsername?: string;
-  /** Instead of TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET_TOKEN. */
+  /** Instead of the token in settings. Without a secret, webhook mode makes a new one each start. */
   credentials?: { botToken?: string; webhookSecretToken?: string };
   /** Telegram user ids that may reach the agent. */
   allowFrom?: number[];
@@ -67,6 +69,14 @@ export interface TelegramOptions {
   chatHistory?: ChatHistory;
   /** Send what the model writes on its way to an answer as it writes it, not only the answer. Off unless true. */
   sendWhileWorking?: boolean;
+  /**
+   * Seconds to wait before handling a text message, so that anything else sent
+   * in the same chat inside that time is handled as one message, joined by a
+   * blank line in the order it arrived. Zero, the default, handles each one on
+   * its own. A share that arrives as two messages (a quote and a comment) is
+   * what this is for. A message carrying a file is never held.
+   */
+  stackWithin?: number;
   mode?: "polling" | "webhook";
   /** Where this server is reachable from outside, for mode "webhook", like "https://agents.example.com". */
   publicUrl?: string;
@@ -116,13 +126,14 @@ export function telegramChannel(options: TelegramOptions = {}): Channel {
   return {
     name: options.name ?? "telegram",
     chatHistory: options.chatHistory,
+    madeWith: JSON.stringify(options),
     start(agent) {
       const name = agent()?.name ?? "";
-      const token = options.credentials?.botToken || process.env.TELEGRAM_BOT_TOKEN || "";
+      const token = options.credentials?.botToken || settings.agents[name]?.telegram || "";
       if (!token) {
         console.error(
           `telegram: ${name} has a Telegram channel but no bot. Message @BotFather in Telegram, send /newbot, ` +
-            "and put the token it gives you in .env as TELEGRAM_BOT_TOKEN. Then restart.",
+            `and put the token it gives you in settings.local.json as "agents": { "${name}": { "telegram": "..." } }.`,
         );
         return { stop: () => {} };
       }
@@ -161,7 +172,7 @@ export function listen(
   const rules: Rules = { allowFrom: options.allowFrom ?? [], inGroups: options.inGroups, chatHistory: options.chatHistory, sendWhileWorking: options.sendWhileWorking };
   const mode = options.mode ?? "polling";
   const path = `/chloe/v1/${name}/${channel}`;
-  const secret = options.credentials?.webhookSecretToken || process.env.TELEGRAM_WEBHOOK_SECRET_TOKEN || randomBytes(24).toString("hex");
+  const secret = options.credentials?.webhookSecretToken || randomBytes(24).toString("hex");
   const allowedTypes = options.uploadPolicy?.allowedMediaTypes ?? ["image/*", "application/pdf", "text/*"];
   const maxBytes = options.uploadPolicy?.maxBytes ?? 10 * 1024 * 1024;
   const stopping = new AbortController();
@@ -180,11 +191,21 @@ export function listen(
     return reply.result as T;
   }
 
-  /** Sending is not stopped with the reading: a turn already under way still answers. */
+  /**
+   * Sending is not stopped with the reading: a turn already under way still
+   * answers. Each piece goes as Telegram's HTML, made from the Markdown the
+   * model wrote, and as the words themselves if Telegram refuses that, so a
+   * formatting slip never loses a reply.
+   */
   async function send(chatId: number, text: string, extra: object = {}): Promise<void> {
-    for (let i = 0; i < text.length; i += MAX_MESSAGE) {
-      const last = i + MAX_MESSAGE >= text.length;
-      await call("sendMessage", { chat_id: chatId, text: text.slice(i, i + MAX_MESSAGE), ...(last ? extra : {}) }, 30, null);
+    const pieces = inPieces(text, MAX_MESSAGE);
+    for (const [i, piece] of pieces.entries()) {
+      const rest = i === pieces.length - 1 ? extra : {};
+      try {
+        await call("sendMessage", { chat_id: chatId, text: telegramHtml(piece), parse_mode: "HTML", ...rest }, 30, null);
+      } catch {
+        await call("sendMessage", { chat_id: chatId, text: piece, ...rest }, 30, null);
+      }
     }
   }
 
@@ -272,10 +293,39 @@ export function listen(
     };
   }
 
+  /** Text waiting for the stacking window to close, by chat: what was said, and the first message it was said in. */
+  const stacking = new Map<string, { parts: string[]; first: TgMessage; timer: ReturnType<typeof setTimeout> }>();
+
   async function onMessage(message: TgMessage): Promise<void> {
     const agent = options.agent();
     const text = message.text ?? message.caption ?? "";
     if (!agent || !message.from || (!text && !message.photo && !message.document)) return;
+    const wait = options.stackWithin ?? 0;
+    if (wait > 0 && text && !message.photo && !message.document) {
+      const key = `${message.chat.id}${message.is_topic_message ? `-${message.message_thread_id}` : ""}`;
+      const held = stacking.get(key);
+      if (held) clearTimeout(held.timer);
+      const parts = held ? [...held.parts, text] : [text];
+      // The first message is the one answered, so the reply sits under the
+      // start of what was sent rather than under its last line.
+      const first = held?.first ?? message;
+      stacking.set(key, {
+        parts,
+        first,
+        timer: setTimeout(() => {
+          stacking.delete(key);
+          void handled(first, parts.join("\n\n")).catch((error) => console.error("telegram:", error));
+        }, wait * 1000),
+      });
+      return;
+    }
+    await handled(message, text);
+  }
+
+  /** One message, or everything stacked into it, from the point the text is settled. */
+  async function handled(message: TgMessage, text: string): Promise<void> {
+    const agent = options.agent();
+    if (!agent || !message.from) return;
     const chatId = message.chat.id;
     const topic = message.is_topic_message ? message.message_thread_id : undefined;
     const extra = {
@@ -394,3 +444,68 @@ export function listen(
     },
   };
 }
+
+/**
+ * A long reply cut into pieces Telegram will take, at a line break where there
+ * is one, so a tag is never cut in half.
+ */
+export function inPieces(text: string, max: number): string[] {
+  const pieces: string[] = [];
+  let rest = text;
+  while (rest.length > max) {
+    const cut = rest.lastIndexOf("\n", max);
+    const at = cut > max / 2 ? cut : max;
+    pieces.push(rest.slice(0, at));
+    rest = rest.slice(at).replace(/^\n/, "");
+  }
+  return [...pieces, rest];
+}
+
+const escape = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/** **bold**, *italic*, ~~struck~~, `code` and [links](https://...) in one line, everything else escaped. */
+function inline(line: string): string {
+  // Code first, and put aside, so nothing inside it is read as bold or a link.
+  const kept: string[] = [];
+  const keep = (html: string) => `\u0000${kept.push(html) - 1}\u0000`;
+  const marked = line
+    .replace(/`([^`]+)`/g, (_, code: string) => keep(`<code>${escape(code)}</code>`))
+    .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (all, words: string, to: string) =>
+      // Only a web or mail address becomes a link, never javascript: or data:.
+      /^(https?:|mailto:)/i.test(to) ? keep(`<a href="${escape(to).replace(/"/g, "&quot;")}">${escape(words)}</a>`) : all,
+    );
+  return escape(marked)
+    .replace(/\*\*(.+?)\*\*/g, "<b>$1</b>")
+    .replace(/(^|[^*\w])\*(?!\s)([^*]+?)\*(?![*\w])/g, "$1<i>$2</i>")
+    .replace(/~~(.+?)~~/g, "<s>$1</s>")
+    .replace(/\u0000(\d+)\u0000/g, (_, i: string) => kept[Number(i)]);
+}
+
+/**
+ * Markdown as the HTML Telegram takes, which is only bold, italics, struck,
+ * code, code blocks, links and quotes. A heading becomes a bold line and a
+ * list item starts with a bullet. Anything else is escaped and shown as
+ * written, so no reply can be refused for a tag Telegram does not know.
+ */
+export function telegramHtml(markdown: string): string {
+  const out: string[] = [];
+  const lines = markdown.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim().startsWith("```")) {
+      const code: string[] = [];
+      for (i++; i < lines.length && !lines[i].trim().startsWith("```"); i++) code.push(lines[i]);
+      out.push(`<pre>${escape(code.join("\n"))}</pre>`);
+    } else if (line.startsWith(">")) {
+      const quote: string[] = [];
+      for (; i < lines.length && lines[i].startsWith(">"); i++) quote.push(inline(lines[i].replace(/^>\s?/, "")));
+      i--;
+      out.push(`<blockquote>${quote.join("\n")}</blockquote>`);
+    } else if (/^#{1,6}\s/.test(line)) {
+      out.push(`<b>${inline(line.replace(/^#+\s*/, "").replace(/\*\*/g, ""))}</b>`);
+    } else {
+      out.push(inline(line.replace(/^(\s*)[-*]\s/, "$1• ")));
+    }
+  }
+  return out.join("\n");
+}

package/core/clock.ts

@@ -20,6 +20,20 @@ export interface Fired {
   parked?: boolean;
 }
 
+/**
+ * A run that did not happen, and which of the two it was. `skipped` is the
+ * same job already going or already waiting on an answer; `failed` is a run
+ * that started and ended in an error, which is written into its own record.
+ */
+export interface NotRun {
+  skipped?: "busy" | "waiting";
+  failed?: string;
+}
+
+export function ran(result: Fired | NotRun): result is Fired {
+  return "runId" in result;
+}
+
 export interface Clock {
   stop(): void;
   /**
@@ -27,9 +41,10 @@ export interface Clock {
    * what a job that declares an `input` shape is started with, and is checked
    * against it before the run exists: a caller that sent the wrong thing gets
    * the error rather than a failed run. `channel` is what the log shows it
-   * came in on, and is "unknown" when left out.
+   * came in on, and is "unknown" when left out. A run that did not happen
+   * hands back why, so a caller can say which of the two it was.
    */
-  fire(agent: Agent, job: Job, input?: unknown, channel?: string): Promise<Fired | undefined>;
+  fire(agent: Agent, job: Job, input?: unknown, channel?: string): Promise<Fired | NotRun>;
   running(): string[];
 }
 
@@ -54,26 +69,27 @@ export function startClock(agents: () => Map<string, Agent>): Clock {
   let lastMinute = "";
 
   /**
-   * Hands back what the run came to, so whoever started it can answer with it.
-   * Nothing when it was skipped, because the same job was already going.
+   * Hands back what the run came to, so whoever started it can answer with it,
+   * or why there is nothing: the same job was already going, or the run
+   * failed.
    *
    * It throws only for input that does not fit the job's shape, which is the
    * caller's mistake and worth telling them about. Anything that goes wrong
    * inside the run is that run's own record, and is logged rather than thrown:
    * the clock has nobody to tell.
    */
-  async function fire(agent: Agent, job: Job, input?: unknown, channel = "unknown"): Promise<Fired | undefined> {
+  async function fire(agent: Agent, job: Job, input?: unknown, channel = "unknown"): Promise<Fired | NotRun> {
     const key = `${agent.name}/${job.id}`;
     if (busy.has(key)) {
       console.warn(`${key}: still running from last time, skipping this one`);
-      return;
+      return { skipped: "busy" };
     }
     // A job waiting on a person is still that job's turn. Starting a second
     // one would ask the same question twice and act on whichever came back
     // first.
     if (job.run && waitingFor(agent.name, job.id)) {
       console.warn(`${key}: still waiting on an answer, skipping this one`);
-      return;
+      return { skipped: "waiting" };
     }
     busy.add(key);
     const began = Date.now();
@@ -88,6 +104,7 @@ export function startClock(agents: () => Map<string, Agent>): Clock {
     } catch (error) {
       if (error instanceof WrongInput) throw error;
       console.error(`${key}: failed`, error);
+      return { failed: (error as Error).message };
     } finally {
       busy.delete(key);
     }

package/core/current.ts

@@ -0,0 +1,19 @@
+// Which run the code running right now belongs to.
+//
+// A tool is called deep inside a turn and is never handed the run it is part
+// of. A write that becomes a commit still has to say which run made it, so
+// the two runners start each run inside `duringRun` and anything below can
+// ask `currentRun()`.
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const current = new AsyncLocalStorage<string>();
+
+/** Runs `work` as part of run `runId`, for everything it awaits. */
+export function duringRun<T>(runId: string, work: () => Promise<T>): Promise<T> {
+  return current.run(runId, work);
+}
+
+/** The run this code is part of, or undefined outside one. */
+export function currentRun(): string | undefined {
+  return current.getStore();
+}

package/core/db.ts

@@ -76,10 +76,30 @@ if (added("runs", "job", "text")) {
   db.exec("update runs set job = source, source = 'schedule' where kind = 'turn' and source not in ('telegram', 'chat', 'api', 'eval', 'studio')");
 }
 db.exec("update runs set source = 'terminal' where source = 'npm run'");
+// The commits the run made, as JSON: [{ "in": "memory" | "folder", "id", "subject" }].
+added("runs", "commits", "text");
 // The tools a reply called, as JSON, so the next turn knows how it was reached.
 added("messages", "used", "text");
 db.exec("create index if not exists runs_parked on runs (parked) where parked is not null");
 
+// When somebody last looked at an agent's changes. One row per agent.
+db.exec("create table if not exists seen (agent text primary key, at text not null)");
+
+/** One commit a run made: in the agent's memory, or in the repo its own folder is in. */
+export interface RunCommit {
+  in: "memory" | "folder";
+  id: string;
+  subject: string;
+}
+
+/** Adds a commit to the run that made it. */
+export function addCommit(runId: string, commit: RunCommit): void {
+  db.prepare("update runs set commits = json_insert(coalesce(commits, '[]'), '$[#]', json(?)) where id = ?").run(
+    JSON.stringify(commit),
+    runId,
+  );
+}
+
 /** Adds the column when it is missing, and says whether it did. */
 function added(table: string, column: string, declaration: string): boolean {
   const there = db.prepare("select 1 from pragma_table_info(?) where name = ?").get(table, column);

package/core/notes.ts

@@ -11,7 +11,7 @@ import { dirname, join } from "node:path";
 
 import type { z } from "zod";
 
-import { STATE } from "./paths.ts";
+import { memoryDir, memoryFolderOf } from "./paths.ts";
 
 /** One JSON file an agent keeps, read and written against a schema. */
 export interface Note<T> {
@@ -21,11 +21,11 @@ export interface Note<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.
+ * A note by name, in that agent's memory. 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`);
+  const path = join(memoryFolderOf(agent), `${name}.json`);
   return {
     path,
     async read() {

package/core/paths.ts

@@ -1,7 +1,9 @@
 // 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.
+// control. What one agent writes is in its memory, and never here.
+import { join } from "node:path";
+
 import { ROOT } from "./root.ts";
 import { setting, settings } from "./settings.ts";
 
@@ -9,9 +11,26 @@ export { ROOT };
 
 // Filled by the loader from what each agent declared, before any tool is bound.
 let folders = new Map<string, string>();
+let memories = new Map<string, string>();
 
-export function setAgentDirs(declared: Map<string, string>): void {
+export function setAgentDirs(declared: Map<string, string>, memory = new Map<string, string>()): void {
   folders = declared;
+  memories = memory;
+}
+
+/** One agent's memory folder, as the loader worked it out. Undefined for an agent not loaded. */
+export function memoryDir(name: string): string | undefined {
+  return memories.get(name);
+}
+
+/**
+ * Where an agent's notes go: its memory folder as the loader worked it out, or
+ * where that folder would be for an agent that has not been loaded. Nothing an
+ * agent writes goes anywhere but its memory, which is why this never falls back
+ * to the state directory.
+ */
+export function memoryFolderOf(name: string): string {
+  return memories.get(name) ?? join(MEMORIES, name);
 }
 
 /** One agent's own folder: its skills, scripts, evals and prompts. */
@@ -22,8 +41,20 @@ export function agentDir(name: string): string {
 }
 
 /**
- * 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.
+ * What the runtime keeps about the agents, as against what they write, which is
+ * MEMORIES: the run history, the account, the tokens and the log of what each
+ * memory served. None of it is ever in git, and two of those are why: a secret
+ * in a repository stays in its history, and the run history is one SQLite file
+ * rewritten every run. Unset, this 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`;
+
+/**
+ * Where the memories are: one folder per agent, and one git repository holding
+ * all of them, so an agent's folder stays source and its notes stay out of the
+ * repository that source is in. Unset, this is `memory/` inside STATE, so one
+ * ignored folder holds everything this box keeps. It is a repository of its own
+ * even so: what the agents write is in git, and nothing else in STATE ever is.
+ */
+export const MEMORIES = setting(settings.memory, "AGENTS_MEMORY") || `${STATE}/memory`;

package/core/root.ts

@@ -6,7 +6,7 @@ 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.
+ * running process. data/ and the settings files are found beside it.
  */
 function findRoot(): string {
   let dir = process.cwd();

package/core/settings.ts

@@ -34,8 +34,13 @@ const schema = z.object({
     .prefault({}),
   email: z
     .object({
-      /** Who carries an agent's mail. Its key is in that provider's own section. */
-      provider: z.enum(["resend"]).default("resend"),
+      /**
+       * Who carries an agent's mail. Its key is in that provider's own
+       * section. "none" writes the message to the log and sends nothing, which
+       * is what a test run and a box with no mail account use. EMAIL_PROVIDER
+       * overrides it for one run.
+       */
+      provider: z.enum(["resend", "none"]).default("resend"),
     })
     .prefault({}),
   /** Sending mail through Resend. */
@@ -64,8 +69,29 @@ const schema = z.object({
       email_from: z.string().default(""),
     })
     .prefault({}),
+  /**
+   * Each agent's own settings, under the name in its `agent.ts`: its channels'
+   * tokens. Read by that name when the channel starts, so renaming an agent
+   * means renaming its entry here, and the server says so when an entry names
+   * no agent.
+   */
+  agents: z
+    .record(
+      z.string(),
+      z
+        .object({
+          /** Its Telegram bot's token, from @BotFather. */
+          telegram: z.string().default(""),
+          /** Its Slack app's two tokens: the bot token (xoxb-...) and the app token (xapp-...). */
+          slack: z.object({ bot_token: z.string().default(""), app_token: z.string().default("") }).strict().prefault({}),
+        })
+        .strict(),
+    )
+    .default({}),
   /** Everything the agents keep: their folders and the run history. Empty means data/ inside the repo. */
   state: z.string().default(""),
+  /** Where the memories are, one folder per agent. Empty means memory/ inside the state folder. */
+  memory: z.string().default(""),
   /** Which node the unit runs. Empty means whichever is on the path at install. */
   node: z.string().default(""),
 });
@@ -109,12 +135,27 @@ export function readSettings(tracked: unknown, local: unknown): Settings {
 }
 
 /**
- * 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()`.
+ * The settings in force: the schema's defaults, then `settings.json`, then
+ * `settings.local.json`. One value can still be beaten by an environment
+ * variable, through `setting()`. The server calls `reloadSettings` when either
+ * file changes, so read a value when it is needed rather than keeping a copy.
+ * `state` and `memory` are the exceptions: where things are kept needs a restart.
  */
 export const settings: Settings = readSettings(read("settings.json"), read("settings.local.json"));
 
+/**
+ * Read both files again, into the same `settings` everything already holds.
+ * Throws, and changes nothing, when the files are not valid.
+ */
+export function reloadSettings(): void {
+  Object.assign(settings, readSettings(read("settings.json"), read("settings.local.json")));
+}
+
+/** The entries in `agents` that name none of these agents: usually one that was renamed. */
+export function unclaimed(names: string[]): string[] {
+  return Object.keys(settings.agents).filter((name) => !names.includes(name));
+}
+
 /**
  * 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.