@chloejs/core 0.2.4 → 0.3.0

package/services/emailService.ts

@@ -20,14 +20,25 @@ export interface EmailSender {
   to: string[];
   /** Prefix put in front of every subject, so an inbox can be filtered. */
   tag?: string;
+  /** Where a reply goes, when not to `from`: a sending address that cannot receive mail needs this. */
+  replyTo?: string[];
+  /**
+   * The body is Markdown: it is sent as HTML with headings, lists, tables and
+   * links, plus a plain text copy without the symbols. Off, it is sent as
+   * written, as plain text only.
+   */
+  markdown?: boolean;
 }
 
 /** One message, ready to go: the tag is already in the subject. */
 export interface Email {
   from: string;
   to: string[];
+  replyTo?: string[];
   subject: string;
+  /** Plain text. */
   body: string;
+  html?: string;
 }
 
 /** Something that can carry an email. Returns the provider's id for it, if it gives one. */
@@ -36,13 +47,13 @@ export interface EmailProvider {
 }
 
 const resend: EmailProvider = {
-  async send({ from, to, subject, body }) {
+  async send({ from, to, replyTo, subject, body, html }) {
     const key = setting(settings.resend.api_key, "RESEND_API_KEY");
     if (!key) throw new Error("No Resend key. Put it in settings.local.json as resend.api_key.");
     const response = await fetch("https://api.resend.com/emails", {
       method: "POST",
       headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
-      body: JSON.stringify({ from, to, subject, text: body }),
+      body: JSON.stringify({ from, to, reply_to: replyTo, subject, text: body, html }),
       signal: AbortSignal.timeout(30_000),
     });
     if (!response.ok) {
@@ -52,22 +63,147 @@ const resend: EmailProvider = {
   },
 };
 
+/**
+ * Carries nothing: the subject and who it was for go to the log and the
+ * message is dropped. What a test run and a box with no mail account use, so
+ * that code which mails can be exercised without anything leaving the box.
+ */
+const none: EmailProvider = {
+  async send({ to, subject }) {
+    console.log(`email (not sent, provider is none): "${subject}" to ${to.join(", ")}`);
+    return {};
+  },
+};
+
 /** Every provider email.provider can name. Adding one is an entry here and in the settings schema. */
-const providers: Record<typeof settings.email.provider, EmailProvider> = { resend };
+const providers: Record<typeof settings.email.provider, EmailProvider> = { resend, none };
 
 /** Sends one email through the configured provider and returns its id. The tag is put in front of the subject. */
 export async function sendEmail(
-  { from, to, tag }: EmailSender,
+  { from, to, tag, replyTo, markdown }: EmailSender,
   subject: string,
   body: string,
 ): Promise<{ sent: true; id?: string; subject: string }> {
   // Refuse rather than send nowhere.
   if (to.length === 0) throw new Error("Nobody to send to. Give the sender at least one address in to.");
-  const { id } = await providers[settings.email.provider].send({
+  const tagged = tag && !subject.startsWith(`[${tag}]`) ? `[${tag}] ${subject}` : subject;
+  const chosen = setting(settings.email.provider, "EMAIL_PROVIDER") as typeof settings.email.provider;
+  const provider = providers[chosen];
+  if (!provider) throw new Error(`No email provider called "${chosen}". It is one of: ${Object.keys(providers).join(", ")}.`);
+  const { id } = await provider.send({
     from,
     to,
-    subject: tag ? `[${tag}] ${subject}` : subject,
-    body,
+    replyTo,
+    subject: tagged,
+    body: markdown ? markdownToText(body) : body,
+    html: markdown ? markdownToHtml(body) : undefined,
   });
-  return { sent: true, id, subject };
+  return { sent: true, id, subject: tagged };
+}
+
+const escape = (s: string) =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
+const LINK = /\[([^\]]+)\]\(([^)]+)\)/g;
+
+function inline(s: string): string {
+  return escape(s)
+    .replace(/`([^`]+)`/g, "<code style='background:#f1f1f1;padding:1px 4px;border-radius:3px'>$1</code>")
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    // Only a web or mail address becomes a link, never javascript: or data:.
+    .replace(LINK, (_, words, to) => (/^(https?:|mailto:)/i.test(to) ? `<a href='${to}'>${words}</a>` : words))
+    .replace(/(?<!["'>=])(https?:\/\/[^\s<)]+)/g, "<a href='$1'>$1</a>");
+}
+
+const cells = (row: string) => row.trim().replace(/^\||\|$/g, "").split("|").map((c) => c.trim());
+const isRule = (row: string[]) => row.every((c) => /^[-: ]*$/.test(c));
+const BULLET = /^\s*[-*] /;
+
+/**
+ * Markdown as email HTML: `##` headings, `-` lists, `|` tables, `>` quotes,
+ * fenced code, **bold**, `code` and links. Lines next to each other are one
+ * paragraph, so a body wrapped at any width reads as prose rather than as a
+ * ragged line per paragraph. Only a blank line starts a new one.
+ */
+export function markdownToHtml(markdown: string): string {
+  const out: string[] = [];
+  const lines = markdown.split("\n");
+  let para: string[] = [];
+  let table: string[][] = [];
+  const endPara = () => {
+    if (para.length) out.push(`<p style='margin:0 0 14px'>${inline(para.join(" "))}</p>`);
+    para = [];
+  };
+  const endTable = () => {
+    const rows = table.filter((r) => !isRule(r));
+    table = [];
+    if (!rows.length) return;
+    const th = "padding:5px 10px;border-bottom:2px solid #d9d9d9;text-align:left";
+    const td = "padding:5px 10px;border-bottom:1px solid #eee";
+    const head = rows[0].map((c) => `<th style='${th}'>${inline(c)}</th>`).join("");
+    const body = rows.slice(1).map((r) => `<tr>${r.map((c) => `<td style='${td}'>${inline(c)}</td>`).join("")}</tr>`);
+    out.push(`<table style='border-collapse:collapse;margin:0 0 16px'><tr>${head}</tr>${body.join("")}</table>`);
+  };
+  for (let i = 0; i < lines.length; ) {
+    const line = lines[i];
+    if (line.trim().startsWith("```")) {
+      endPara();
+      endTable();
+      const code: string[] = [];
+      for (i++; i < lines.length && !lines[i].trim().startsWith("```"); i++) code.push(escape(lines[i]));
+      out.push(`<pre style='background:#f6f6f6;padding:10px;overflow:auto'>${code.join("\n")}</pre>`);
+      i++;
+    } else if (line.trimStart().startsWith("|") && line.split("|").length > 2) {
+      endPara();
+      table.push(cells(line));
+      i++;
+    } else if (!line.trim()) {
+      endPara();
+      endTable();
+      i++;
+    } else if (line.startsWith("#")) {
+      endPara();
+      endTable();
+      const size = line.startsWith("###") ? 15 : 17;
+      out.push(`<div style='font-size:${size}px;font-weight:700;margin:22px 0 10px'>${inline(line.replace(/^#+/, "").trim())}</div>`);
+      i++;
+    } else if (BULLET.test(line)) {
+      endPara();
+      endTable();
+      const items: string[] = [];
+      while (i < lines.length && BULLET.test(lines[i])) {
+        let item = lines[i++].replace(BULLET, "");
+        while (i < lines.length && lines[i].trim() && !/^\s*[-*] |^#|^\s*\||^> /.test(lines[i])) item += ` ${lines[i++].trim()}`;
+        items.push(`<li style='margin:0 0 6px'>${inline(item)}</li>`);
+      }
+      out.push(`<ul style='margin:0 0 14px;padding-left:22px'>${items.join("")}</ul>`);
+    } else if (line.startsWith("> ")) {
+      endPara();
+      endTable();
+      const quote: string[] = [];
+      while (i < lines.length && lines[i].startsWith("> ")) quote.push(lines[i++].slice(2).trim());
+      out.push(`<blockquote style='margin:0 0 14px;padding-left:14px;border-left:3px solid #ccc'>${inline(quote.join(" "))}</blockquote>`);
+    } else {
+      endTable();
+      para.push(line.trim());
+      i++;
+    }
+  }
+  endPara();
+  endTable();
+  return `<div style="font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:15px;line-height:1.55;max-width:640px">${out.join("\n")}</div>`;
+}
+
+/** The same Markdown as plain text: no `#`, `**` or backticks, a table row as `a: b`, a link as `words (address)`. */
+export function markdownToText(markdown: string): string {
+  return markdown
+    .split("\n")
+    .flatMap((line) => {
+      if (line.trimStart().startsWith("|")) {
+        const row = cells(line);
+        return isRule(row) ? [] : [`  ${row.filter(Boolean).join(": ")}`];
+      }
+      return [line.replace(/^#+\s*/, "").replace(LINK, "$1 ($2)").replace(/\*\*/g, "").replace(/`/g, "")];
+    })
+    .join("\n");
 }

package/services/filesService.ts

@@ -10,11 +10,11 @@
 // skill, which is text you can edit, not code that needs a restart.
 //
 // What they do enforce is the edge of the folder, through confine().
-import { execFile } from "node:child_process";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
 import { confine } from "#chloe/core/confine.ts";
+import { commitPaths, noteCommit, type Place } from "./historyService.ts";
 import { run } from "./runService.ts";
 
 /** List a folder. `path` is relative to `root`, and omitting it means the top. */
@@ -65,32 +65,43 @@ export async function searchFiles(root: string, query: string, folder?: string)
 }
 
 /**
- * Write one file, replacing it. `commit` makes the write a git commit, for a
- * folder that is a repo, and then `message` is required.
+ * Write one file, replacing it, or with `append` adding to the end of it on a
+ * line of its own, so a long file that only grows is never written out whole.
+ * `commit` makes the write a git commit of that file alone, for a folder in a
+ * repo, and then `message` is required. `author` is the agent it is written
+ * under, and `in` which of its places this is, so the run writing it lists
+ * the commit. Without an author it is this box's own git name.
  */
 export async function writeFiles(
   root: string,
   path: string,
   content: string,
-  { commit = false, message }: { commit?: boolean; message?: string } = {},
+  {
+    commit = false,
+    message,
+    append = false,
+    author,
+    in: place,
+  }: { commit?: boolean; message?: string; append?: boolean; author?: string; in?: Place } = {},
 ) {
   if (commit && (message ?? "").length < 10) {
     throw new Error("This folder is a repo, so every write needs a commit message.");
   }
   const resolved = confine(root, path);
   await mkdir(dirname(resolved), { recursive: true });
-  await writeFile(resolved, content, "utf8");
+  if (append) {
+    const before = await readFile(resolved, "utf8").catch(() => "");
+    await appendFile(resolved, before && !before.endsWith("\n") ? `\n${content}` : content, "utf8");
+  } else {
+    await writeFile(resolved, content, "utf8");
+  }
   if (!commit) return { path: resolved, bytes: content.length };
-  const committed = await new Promise<string>((done) => {
-    execFile("git", ["-C", root, "add", "--", resolved], { timeout: 30_000 }, () =>
-      execFile(
-        "git",
-        ["-C", root, "commit", "-m", message!, "--", resolved],
-        { timeout: 30_000, encoding: "utf8" },
-        (error: unknown, out: string, err: string) =>
-          done(error ? `not committed: ${err || out}` : out.trim()),
-      ),
-    );
-  });
+  const committed = await commitPaths(root, [resolved], { message: message!, author }).then(
+    (id) => {
+      if (place) noteCommit(place, id, message!);
+      return id ? id.slice(0, 12) : "nothing changed, so nothing was committed";
+    },
+    (error: unknown) => `not committed: ${error instanceof Error ? error.message : String(error)}`,
+  );
   return { path: resolved, bytes: content.length, commit: committed };
 }

package/services/historyService.ts

@@ -0,0 +1,372 @@
+// What changed in an agent's folders, as git history.
+//
+// Two places can hold it: the agent's memory, a folder in the repository every
+// memory shares, and the agent's own folder (instructions, skills, jobs),
+// usually inside the repository the agents are written in. So a place is a
+// folder inside a repository and never a repository, and everything here is
+// scoped to that folder: what is listed, what is shown, and above all what is
+// committed, because the folder beside it belongs to another agent. A commit made
+// for an agent is written under the agent's name with an empty email, and
+// ends with the run that made it, `Run: <id>`, so a file's history leads back
+// to the run and the run's record lists its commits.
+//
+// Every call is git with an argument list, never a shell string.
+import { execFile } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { appendFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+
+import { currentRun } from "#chloe/core/current.ts";
+import { addCommit, db, type RunCommit } from "#chloe/core/db.ts";
+import type { Agent } from "#chloe/load/load.ts";
+
+/** Which of an agent's two places a commit is in. */
+export type Place = RunCommit["in"];
+
+interface Git {
+  code: number;
+  out: string;
+  err: string;
+}
+
+/**
+ * One git command in `cwd`. `author` makes the commit that agent's, author and
+ * committer both, so it works on a box whose git has no name set. It goes in
+ * git's own environment variables, because those beat any setting. Never throws.
+ */
+async function git(cwd: string, args: string[], author?: string): Promise<Git> {
+  const env = author
+    ? { ...process.env, GIT_AUTHOR_NAME: author, GIT_AUTHOR_EMAIL: "", GIT_COMMITTER_NAME: author, GIT_COMMITTER_EMAIL: "" }
+    : process.env;
+  const unsigned = author ? ["-c", "commit.gpgsign=false"] : [];
+  for (let attempt = 0; ; attempt++) {
+    const result = await new Promise<Git>((done) =>
+      execFile(
+        "git",
+        [...unsigned, ...args],
+        { cwd, env, encoding: "utf8", maxBuffer: 32 << 20, timeout: 60_000 },
+        (error, out, err) => done({ code: error ? Number((error as { code?: unknown }).code) || 1 : 0, out: out ?? "", err: err ?? "" }),
+      ),
+    );
+    // Two writes to one repo at the same moment: the second finds the first's lock.
+    if (result.code === 0 || !result.err.includes("index.lock") || attempt === 5) return result;
+    await new Promise((wait) => setTimeout(wait, 200));
+  }
+}
+
+async function gitOrThrow(cwd: string, args: string[], author?: string): Promise<string> {
+  const result = await git(cwd, args, author);
+  if (result.code !== 0) throw new Error((result.err || result.out).trim().split("\n")[0] || `git ${args[0]} failed`);
+  return result.out;
+}
+
+/** The top of the repository a folder is in, or undefined when it is in none. */
+export async function repoOf(folder: string): Promise<string | undefined> {
+  if (!existsSync(folder)) return undefined;
+  const found = await git(folder, ["rev-parse", "--show-toplevel"]);
+  return found.code === 0 ? realpathSync(found.out.trim()) : undefined;
+}
+
+/**
+ * Whether a folder is the top of a repository of its own. Being inside one is
+ * not enough: asked from there, git answers for the repository around it.
+ */
+export async function isRepoTop(folder: string): Promise<boolean> {
+  const top = await repoOf(folder);
+  return top !== undefined && top === realpathSync(folder);
+}
+
+function withRun(message: string, runId: string | undefined): string {
+  return runId ? `${message.trim()}\n\nRun: ${runId}` : message.trim();
+}
+
+/**
+ * Commits these paths and nothing else: whatever else is changed or staged in
+ * the repository stays as it was, so somebody's work in progress stays theirs.
+ * Answers the new commit's id, or undefined when those paths had not changed.
+ */
+export async function commitPaths(
+  folder: string,
+  paths: string[],
+  { message, author, runId = currentRun() }: { message: string; author?: string; runId?: string },
+): Promise<string | undefined> {
+  const repo = await repoOf(folder);
+  if (!repo) throw new Error(`${folder} is not in a git repository.`);
+  if (paths.length === 0) return undefined;
+  const inRepo = paths.map((one) => relative(repo, resolve(realpathSync(folder), one)));
+  await gitOrThrow(repo, ["add", "-A", "--", ...inRepo]);
+  if ((await git(repo, ["diff", "--cached", "--quiet", "--", ...inRepo])).code === 0) return undefined;
+  await gitOrThrow(repo, ["commit", "-q", "-m", withRun(message, runId), "--", ...inRepo], author);
+  return (await gitOrThrow(repo, ["rev-parse", "HEAD"])).trim();
+}
+
+/** Commits everything that changed in a repository. Undefined when nothing had. */
+export async function commitAll(
+  repo: string,
+  { message, author, runId }: { message: string; author?: string; runId?: string },
+): Promise<string | undefined> {
+  await gitOrThrow(repo, ["add", "-A"]);
+  if ((await git(repo, ["diff", "--cached", "--quiet"])).code === 0) return undefined;
+  await gitOrThrow(repo, ["commit", "-q", "-m", withRun(message, runId)], author);
+  return (await gitOrThrow(repo, ["rev-parse", "HEAD"])).trim();
+}
+
+/** Whether a file has changes nobody has committed, including being new and never added. */
+export async function uncommitted(file: string): Promise<boolean> {
+  const repo = await repoOf(dirname(file));
+  if (!repo) return false;
+  const status = await git(repo, ["status", "--porcelain", "--", relative(repo, file)]);
+  return status.out.trim() !== "";
+}
+
+/**
+ * Makes a folder a repository of its own and commits what is already in it,
+ * under `author`. A repository the folder sits inside is told to leave it
+ * alone, in its own `info/exclude`, so a "commit all" there never takes it.
+ */
+export async function makeRepo(folder: string, author: string): Promise<void> {
+  await mkdir(folder, { recursive: true });
+  if (await isRepoTop(folder)) return;
+  const outer = await repoOf(folder);
+  await gitOrThrow(folder, ["init", "-q", "-b", "main"]);
+  if (outer) {
+    const exclude = resolve(outer, (await gitOrThrow(outer, ["rev-parse", "--git-path", "info/exclude"])).trim());
+    const line = `/${relative(outer, realpathSync(folder))}/`;
+    const already = await readFile(exclude, "utf8").catch(() => "");
+    if (!already.split("\n").includes(line)) {
+      await mkdir(dirname(exclude), { recursive: true });
+      await appendFile(exclude, `${already && !already.endsWith("\n") ? "\n" : ""}${line}\n`);
+    }
+  }
+  await commitAll(folder, { message: "What was here when this folder started keeping its history", author });
+}
+
+/**
+ * The repository a memory's history is in: the one the memory folder is the top
+ * of, or the one its parent is the top of, which is the repository every agent's
+ * memory shares. Anywhere deeper inside a repository has no history here, on
+ * purpose. Being inside a repository is not enough: asked from there, git
+ * answers for whatever repository is around it, so a memory somebody keeps in
+ * their source tree would show their work in progress as its own changes and
+ * push their branch off the box.
+ */
+export async function memoryRepo(agent: Agent): Promise<string | undefined> {
+  const top = await repoOf(agent.memory.folder);
+  if (!top) return undefined;
+  const own = realpathSync(agent.memory.folder);
+  return top === own || top === dirname(own) ? top : undefined;
+}
+
+/** Whether this agent's memory is committed once a run ends. See Memory in load/load.ts. */
+function eachRun(agent: Agent): boolean {
+  return agent.memory.commit === "each run";
+}
+
+/**
+ * Before a run: whatever changed in the memory since the last run ended was
+ * done by somebody else, so it is committed under this box's own git name and
+ * the run's commit holds only the run's work. Skipped while another run of the
+ * same agent is going, because then what changed is that run's.
+ */
+export async function beforeRun(agent: Agent, runId: string): Promise<void> {
+  if (!eachRun(agent) || !(await memoryRepo(agent))) return;
+  const busy = db
+    .prepare("select 1 from runs where agent = ? and finished is null and parked is null and id != ? limit 1")
+    .get(agent.name, runId);
+  if (busy) return;
+  await commitPaths(agent.memory.folder, ["."], { message: "Changed outside a run", runId: undefined }).catch((error: unknown) =>
+    console.error(`${agent.name}: committing what changed outside a run failed:`, error instanceof Error ? error.message : error),
+  );
+}
+
+/** A commit's first line: what the run was, and what it said or why it stopped. */
+function subjectFor({ job, source, summary, error }: RunEnd): string {
+  const said = error ? `stopped: ${error.split("\n")[0]}` : summary?.trim() || "finished";
+  const line = `${job || source}: ${said}`;
+  return line.length > 100 ? `${line.slice(0, 99).trimEnd()}…` : line;
+}
+
+/** How a run ended, for its commit message. */
+export interface RunEnd {
+  job?: string | null;
+  source: string;
+  summary?: string | null;
+  error?: string | null;
+}
+
+/**
+ * After a run, or when it stops to wait for somebody: everything that changed
+ * in the memory is committed under the agent's name, and the run keeps the
+ * commit. Never throws, because the run's work is already done: a commit that
+ * failed is said in the service's log.
+ */
+export async function afterRun(agent: Agent, runId: string, end: RunEnd): Promise<void> {
+  try {
+    if (!eachRun(agent) || !(await memoryRepo(agent))) return;
+    const subject = subjectFor(end);
+    const id = await commitPaths(agent.memory.folder, ["."], { message: subject, author: agent.name, runId });
+    if (id) addCommit(runId, { in: "memory", id, subject });
+  } catch (error) {
+    console.error(`${agent.name}: committing run ${runId} failed:`, error instanceof Error ? error.message : error);
+  }
+}
+
+/** Records a commit made during a run, on that run. */
+export function noteCommit(place: Place, id: string | undefined, subject: string): void {
+  const runId = currentRun();
+  if (runId && id) addCommit(runId, { in: place, id, subject: subject.split("\n")[0] });
+}
+
+/** One commit, as the site lists it. Paths are inside the place it is in. */
+export interface Change {
+  in: Place;
+  id: string;
+  at: string;
+  by: string;
+  subject: string;
+  /** The run that made it, when a run did. */
+  run?: string;
+  files: { path: string; status: string }[];
+}
+
+/** Where a place's history is: the repository, and the agent's part of it. */
+async function whereIs(agent: Agent, place: Place): Promise<{ repo: string; under: string } | undefined> {
+  const folder = place === "memory" ? agent.memory.folder : agent.folder;
+  const repo = place === "memory" ? await memoryRepo(agent) : await repoOf(agent.folder);
+  return repo && existsSync(folder) ? { repo, under: relative(repo, realpathSync(folder)) } : undefined;
+}
+
+function inside(under: string, path: string): string {
+  return under ? join(under, path) : path;
+}
+
+function outOf(under: string, path: string): string {
+  return under && path.startsWith(`${under}/`) ? path.slice(under.length + 1) : path;
+}
+
+const FORMAT = "--format=%x1e%H%x1f%aI%x1f%an%x1f%s%x1f%b%x1f";
+
+function parseLog(text: string, place: Place, under: string): Change[] {
+  return text
+    .split("\x1e")
+    .filter((chunk) => chunk.trim())
+    .map((chunk) => {
+      const [id, at, by, subject, body, names = ""] = chunk.split("\x1f");
+      return {
+        in: place,
+        id,
+        at: new Date(at).toISOString(),
+        by,
+        subject,
+        run: body.match(/^Run: (\S+)$/m)?.[1],
+        files: names
+          .split("\n")
+          .filter((line) => line.includes("\t"))
+          .map((line) => {
+            const [status, path] = line.split("\t");
+            return { path: outOf(under, path), status: status.trim() };
+          }),
+      };
+    });
+}
+
+/**
+ * The commits in one or both places, newest first: every commit to the memory,
+ * and every commit to the repository that touched the agent's own folder.
+ * `path` narrows it to one file, inside that place.
+ */
+export async function changes(
+  agent: Agent,
+  { place, path, limit = 50 }: { place?: Place; path?: string; limit?: number } = {},
+): Promise<Change[]> {
+  const places: Place[] = place ? [place] : ["memory", "folder"];
+  const found: Change[] = [];
+  for (const one of places) {
+    const where = await whereIs(agent, one);
+    if (!where) continue;
+    const scope = path ? inside(where.under, path) : where.under;
+    const log = await git(where.repo, [
+      "log",
+      `-${limit}`,
+      "--no-renames",
+      "--name-status",
+      FORMAT,
+      ...(scope ? ["--", scope] : []),
+    ]);
+    if (log.code === 0) found.push(...parseLog(log.out, one, where.under));
+  }
+  return found.sort((a, b) => b.at.localeCompare(a.at)).slice(0, limit);
+}
+
+/** One commit, with its diff, cut to the agent's own part of the repository. */
+export async function change(agent: Agent, place: Place, id: string): Promise<(Change & { diff: string }) | undefined> {
+  const where = await whereIs(agent, place);
+  if (!where || !/^[0-9a-f]{4,40}$/.test(id)) return undefined;
+  const scope = where.under ? ["--", where.under] : [];
+  const about = await git(where.repo, ["show", "--no-renames", "--name-status", FORMAT, id, ...scope]);
+  if (about.code !== 0) return undefined;
+  const [one] = parseLog(about.out, place, where.under);
+  if (!one) return undefined;
+  const shown = await git(where.repo, ["show", "--format=", "--no-renames", "--patch", id, ...scope]);
+  const diff = shown.out.length > 400_000 ? `${shown.out.slice(0, 400_000)}\n...[cut here]` : shown.out;
+  return { ...one, diff };
+}
+
+/**
+ * Undoes one commit: every file it touched goes back to how it was before it,
+ * and that is committed under this box's git name. Refused when a file has
+ * changed since, because putting it back would lose that later change too.
+ */
+export async function undo(agent: Agent, place: Place, id: string): Promise<{ id: string | undefined; files: string[] }> {
+  const where = await whereIs(agent, place);
+  const found = where && (await change(agent, place, id));
+  if (!where || !found) throw new Error("There is no such change.");
+  const parents = (await gitOrThrow(where.repo, ["rev-list", "--parents", "-n", "1", found.id])).trim().split(" ").slice(1);
+  if (parents.length === 0) throw new Error("This is the first commit there is, so there is nothing before it to go back to.");
+  if (parents.length > 1) throw new Error("This commit joins two histories, so it cannot be undone from here.");
+
+  const touched = found.files.map((file) => ({ ...file, inRepo: inside(where.under, file.path) }));
+  for (const file of touched) {
+    const now = await readFile(join(where.repo, file.inRepo)).catch(() => undefined);
+    const then = file.status === "D" ? undefined : await showFile(where.repo, found.id, file.inRepo);
+    if ((now === undefined) !== (then === undefined) || (now && then && !now.equals(then))) {
+      throw new Error(`${file.path} has changed since, so undoing this would lose that change. Undo the later change first.`);
+    }
+  }
+  for (const file of touched) {
+    const before = file.status === "A" ? undefined : await showFile(where.repo, parents[0], file.inRepo);
+    const at = join(where.repo, file.inRepo);
+    if (before === undefined) await rm(at, { force: true });
+    else {
+      await mkdir(dirname(at), { recursive: true });
+      await writeFile(at, before);
+    }
+  }
+  const undone = await commitPaths(
+    where.repo,
+    touched.map((file) => file.inRepo),
+    { message: `Undo "${found.subject}"\n\nUndoes: ${found.id}`, runId: undefined },
+  );
+  return { id: undone, files: touched.map((file) => file.path) };
+}
+
+/** A file's bytes at a commit, or undefined when it was not there. */
+async function showFile(repo: string, id: string, path: string): Promise<Buffer | undefined> {
+  return new Promise((done) =>
+    execFile("git", ["show", `${id}:${path}`], { cwd: repo, encoding: "buffer", maxBuffer: 64 << 20 }, (error, out) =>
+      done(error ? undefined : (out as Buffer)),
+    ),
+  );
+}
+
+/** When somebody last looked at this agent's changes, or undefined when nobody has. */
+export function seenAt(agent: string): string | undefined {
+  return (db.prepare("select at from seen where agent = ?").get(agent) as { at?: string } | undefined)?.at;
+}
+
+/** Everything this agent has changed up to now has been looked at. */
+export function markSeen(agent: string): string {
+  const at = new Date().toISOString();
+  db.prepare("insert into seen (agent, at) values (?, ?) on conflict (agent) do update set at = excluded.at").run(agent, at);
+  return at;
+}

package/services/index.ts

@@ -9,7 +9,7 @@
 // name here is publishing it.
 
 export { run, type Result } from "./runService.ts";
-export { sendEmail, type EmailSender } from "./emailService.ts";
+export { markdownToHtml, markdownToText, sendEmail, type EmailSender } from "./emailService.ts";
 export { readEmailMessages, readOneEmailMessage, type Message as Mail } from "./gmailService.ts";
 export { listFiles, readFiles, searchFiles, writeFiles } from "./filesService.ts";
 export { listScripts, runScripts } from "./scriptsService.ts";