@chloejs/core 0.2.0

package/serve/login.ts

@@ -0,0 +1,299 @@
+// The login in front of the page: one account, made on the first visit.
+//
+// Nothing is configured to set this up. A fresh copy of chloe has no account,
+// so the first person to open the page is asked to choose a username and a
+// password, and once one exists that door is shut. Changing it afterwards means
+// deleting the file below, which is deliberate: it takes a shell on the box.
+//
+// Hand rolled on node:crypto, scrypt for the password and HMAC-SHA256 for the
+// cookie, because the alternative is a dependency for forty lines.
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import crypto from "node:crypto";
+import type { IncomingMessage } from "node:http";
+
+import { STATE } from "#chloe/core/paths.ts";
+import { checkToken, type Token } from "./tokens.ts";
+import { lockedOut } from "./alerts.ts";
+
+/** The one account, beside the run history, mode 600. Not in source control. */
+const FILE = `${STATE}/login.json`;
+
+export const COOKIE = "chloe_session";
+
+/** A week. Long enough not to be a chore, short enough that a stolen cookie dies. */
+const LASTS = 7 * 24 * 60 * 60;
+
+/** Five wrong passwords from one address buys fifteen minutes of nothing. */
+const TRIES = 5;
+const WINDOW = 15 * 60 * 1000;
+const LOCKED = 15 * 60 * 1000;
+
+interface Account {
+  username: string;
+  password: string;
+  /** Signs the session cookie. Made with the account, so a restart keeps people signed in. */
+  secret: string;
+}
+
+let account: Account | null | undefined;
+
+function read(): Account | null {
+  if (account !== undefined) return account;
+  try {
+    account = JSON.parse(readFileSync(FILE, "utf8")) as Account;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    account = null;
+  }
+  return account;
+}
+
+export function hasAccount(): boolean {
+  return Boolean(read());
+}
+
+/**
+ * The account this copy will have, from the setup page. Throws if one already
+ * exists: the first visit wins, and every visit after it is refused.
+ */
+export function createAccount(username: string, password: string): void {
+  if (hasAccount()) throw new Error("An account already exists.");
+  const who = username.trim();
+  if (!who) throw new Error("Choose a username.");
+  if (password.length < 8) throw new Error("The password must be at least 8 characters.");
+  const made: Account = {
+    username: who,
+    password: hash(password),
+    secret: crypto.randomBytes(32).toString("base64url"),
+  };
+  mkdirSync(STATE, { recursive: true });
+  writeFileSync(FILE, JSON.stringify(made, null, 2), { mode: 0o600 });
+  chmodSync(FILE, 0o600);
+  account = made;
+}
+
+/**
+ * The cookie value for a correct username and password, or the reason it was
+ * refused. The address is what the lockout counts, so one person guessing does
+ * not lock everybody out.
+ */
+export function signIn(username: string, password: string, from: string): string {
+  const held = read();
+  if (!held) throw new Error("There is no account yet.");
+  const wait = lockedFor(from);
+  if (wait) throw new Error(`Too many tries. Try again in ${Math.ceil(wait / 60)} minutes.`);
+  if (!same(username.trim(), held.username) || !check(password, held.password)) {
+    countFailure(from);
+    throw new Error("Wrong username or password.");
+  }
+  failures.delete(from);
+  return sign(held);
+}
+
+/**
+ * Who is making this request. Two different things can be true, and the
+ * difference is the whole of the authorisation this runtime has:
+ *
+ *   account  somebody signed in on this box. Can do everything.
+ *   token    another system holding a token. Read, plus the agents that bind
+ *            an api channel. Cannot write files, make tokens or revoke them.
+ *
+ * A browser carries the account session as a cookie. Anything that is not a
+ * browser sends either the same session value or a token as
+ * `Authorization: Bearer`, and which one it is decides what it may do.
+ */
+export type Caller = { kind: "account" } | { kind: "token"; token: Token } | null;
+
+export function caller(request: IncomingMessage): Caller {
+  const held = read();
+  const values = carried(request);
+  if (held && values.some((value) => holds(value, held))) return { kind: "account" };
+  for (const value of values) {
+    const token = checkToken(value);
+    if (token) return { kind: "token", token };
+  }
+  return null;
+}
+
+/** Whether this request carries anything at all this copy will accept. */
+export function signedIn(request: IncomingMessage): boolean {
+  return caller(request) !== null;
+}
+
+/** The session values on a request: the cookie, then the bearer header. */
+function carried(request: IncomingMessage): string[] {
+  const found: string[] = [];
+  const cookie = cookies(request.headers.cookie)[COOKIE];
+  if (cookie) found.push(cookie);
+  const header = request.headers.authorization ?? "";
+  if (header.toLowerCase().startsWith("bearer ")) found.push(header.slice(7).trim());
+  return found;
+}
+
+/** Whether one value is a session this copy signed, for this account, still in date. */
+function holds(value: string, held: Account): boolean {
+  const dot = value.lastIndexOf(".");
+  if (dot <= 0) return false;
+  const body = value.slice(0, dot);
+  const expected = crypto.createHmac("sha256", held.secret).update(body).digest("base64url");
+  if (!same(value.slice(dot + 1), expected)) return false;
+  try {
+    const inside = JSON.parse(Buffer.from(body, "base64url").toString("utf8")) as { who: string; until: number };
+    return inside.until > Math.floor(Date.now() / 1000) && same(inside.who, held.username);
+  } catch {
+    return false;
+  }
+}
+
+/** The Set-Cookie for a session, or for ending one when the value is empty. */
+export function setCookie(value: string, secure: boolean): string {
+  const rest = `Path=/; HttpOnly; SameSite=Lax${secure ? "; Secure" : ""}`;
+  return value ? `${COOKIE}=${value}; Max-Age=${LASTS}; ${rest}` : `${COOKIE}=; Max-Age=0; ${rest}`;
+}
+
+/**
+ * A cookie for something already running on this box, like `npm run agent`.
+ * It reads the account file, which needs the account's own user, so this is
+ * not a way past the login: it is the same permission, said over HTTP.
+ */
+export function ownCookie(): string {
+  const held = read();
+  if (!held) throw new Error(`There is no account yet. Open the page and make one.`);
+  return `${COOKIE}=${sign(held)}`;
+}
+
+/**
+ * Something signed with the account's secret, for a purpose other than a
+ * session. The purpose is part of what is signed, so a value made for one
+ * purpose can never be passed off as another, and in particular never as a
+ * session. Dies with the account, like everything signed here.
+ */
+export function seal(purpose: string, payload: object): string {
+  const held = read();
+  if (!held) throw new Error("There is no account yet, so nothing can be signed.");
+  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  return `${body}.${crypto.createHmac("sha256", held.secret).update(`${purpose}:${body}`).digest("base64url")}`;
+}
+
+/** The payload a `seal` made for this purpose, or null when it is not one. */
+export function unseal<T>(purpose: string, value: string): T | null {
+  const held = read();
+  if (!held) return null;
+  const dot = value.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const body = value.slice(0, dot);
+  const expected = crypto.createHmac("sha256", held.secret).update(`${purpose}:${body}`).digest("base64url");
+  if (!same(value.slice(dot + 1), expected)) return null;
+  try {
+    return JSON.parse(Buffer.from(body, "base64url").toString("utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+function sign(held: Account): string {
+  const body = Buffer.from(
+    JSON.stringify({ who: held.username, until: Math.floor(Date.now() / 1000) + LASTS }),
+  ).toString("base64url");
+  return `${body}.${crypto.createHmac("sha256", held.secret).update(body).digest("base64url")}`;
+}
+
+/**
+ * scrypt:N:r:p:salt:hash, colon separated rather than the usual $ separated
+ * form: some environment loaders read $16384 as a variable and quietly cut the
+ * hash in half, which is a login that always fails and never says why.
+ */
+function hash(password: string): string {
+  const N = 16384, r = 8, p = 1;
+  const salt = crypto.randomBytes(16);
+  const made = crypto.scryptSync(password.normalize("NFKC"), salt, 32, { N, r, p });
+  return `scrypt:${N}:${r}:${p}:${salt.toString("base64")}:${made.toString("base64")}`;
+}
+
+function check(password: string, stored: string): boolean {
+  try {
+    const [scheme, N, r, p, salt, expected] = stored.split(":");
+    if (scheme !== "scrypt") return false;
+    const want = Buffer.from(expected, "base64");
+    const got = crypto.scryptSync(password.normalize("NFKC"), Buffer.from(salt, "base64"), want.length, {
+      N: Number(N), r: Number(r), p: Number(p),
+    });
+    return crypto.timingSafeEqual(got, want);
+  } catch {
+    return false;
+  }
+}
+
+/** Compares without letting the time it takes say how much of it matched. */
+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);
+}
+
+// In this process, so a restart clears it.
+const failures = new Map<string, { count: number; first: number; until: number }>();
+
+function lockedFor(from: string): number {
+  const seen = failures.get(from);
+  if (!seen) return 0;
+  return seen.until > Date.now() ? Math.ceil((seen.until - Date.now()) / 1000) : 0;
+}
+
+function countFailure(from: string): void {
+  const now = Date.now();
+  const seen = failures.get(from);
+  if (!seen || now - seen.first > WINDOW) return void failures.set(from, { count: 1, first: now, until: 0 });
+  seen.count += 1;
+  if (seen.count >= TRIES) {
+    Object.assign(seen, { count: 0, first: now, until: now + LOCKED });
+    lockedOut(from);
+  }
+}
+
+/**
+ * Who this request is really from, for the lockout and the audit log.
+ *
+ * The socket address is the proxy's, because this binds loopback and something
+ * is always in front. So it comes from a header, and the only question that
+ * matters is which part of which header the caller cannot write.
+ *
+ * `x-forwarded-for` is a list that every hop APPENDS to. So whatever the client
+ * sent arrives at the front, and the entry the proxy in front added is at the
+ * end. The first entry is therefore the one part of it a stranger controls: a
+ * caller sending `x-forwarded-for: 1.2.3.4` and changing it each time would
+ * never be locked out, and could lock anybody out by borrowing their address.
+ * Read the last entry, which is the address the proxy in front actually saw.
+ *
+ * `cf-connecting-ip` is better still where it exists, because Cloudflare
+ * overwrites rather than appends, so a client cannot put anything in it. It is
+ * preferred, and without it the last forwarded entry is the fallback: behind a
+ * CDN that is the CDN's own address, which makes the lockout coarse, but coarse
+ * and honest beats precise and forgeable.
+ *
+ * All of this is only as good as the proxy in front, which is the point of
+ * binding loopback: nothing else can reach this port to set these headers.
+ */
+export function from(request: IncomingMessage): string {
+  const head = (name: string): string[] => {
+    const value = request.headers[name];
+    return (Array.isArray(value) ? value[0] : value)?.split(",").map((one) => one.trim()).filter(Boolean) ?? [];
+  };
+  const cloudflare = head("cf-connecting-ip")[0];
+  const forwarded = head("x-forwarded-for").at(-1);
+  return cloudflare || forwarded || request.socket.remoteAddress || "unknown";
+}
+
+/** True when the proxy in front is speaking HTTPS, so the cookie can be Secure. */
+export function overHttps(request: IncomingMessage): boolean {
+  return request.headers["x-forwarded-proto"] === "https";
+}
+
+function cookies(header: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const one of (header ?? "").split(";")) {
+    const at = one.indexOf("=");
+    if (at > 0) out[one.slice(0, at).trim()] = one.slice(at + 1).trim();
+  }
+  return out;
+}

package/serve/memory.ts

@@ -0,0 +1,372 @@
+// Where an agent remembers things, browsed and edited from the site.
+//
+// Not to be confused with model/memory.ts, which is the last few messages of a
+// conversation. This is a folder: the one an agent reads and writes between
+// runs. Every agent has one, and unless its definition says otherwise it is
+// that agent's own folder under the state directory. An agent that shares a
+// folder with a person, like one that keeps somebody's notes, says where.
+//
+// Every file served is written down first, and that is the point rather than a
+// detail. Reading these files from a shell is not recorded, because a shell on
+// the box is already the whole of the box. Reading them over HTTP is recorded,
+// because HTTP is the part somebody else could come through, and a log of what
+// was served is the only way to answer afterwards what was taken. Do not make
+// the log optional or best effort: a read that could not be recorded is
+// refused instead.
+import { execFile } from "node:child_process";
+import { appendFile, mkdir, readFile, rename as move, rm, stat } from "node:fs/promises";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, extname } from "node:path";
+import { promisify } from "node:util";
+
+import { confine, unreachable } from "#chloe/core/confine.ts";
+import type { Agent } from "#chloe/load/load.ts";
+import { list, read, write } from "#chloe/do/files.ts";
+import { STATE } from "#chloe/core/paths.ts";
+import { BadRequest } from "./errors.ts";
+import { noteHead } from "./page.ts";
+
+const git = promisify(execFile);
+
+/** Deep enough for a folder of writing, and an end to it if something links in a circle. */
+const DEPTH = 8;
+
+const JUNK = ["node_modules", "__pycache__"];
+
+export interface Entry {
+  name: string;
+  path: string;
+  dir: boolean;
+  /** Bytes, for a file. */
+  size?: number;
+  /** When it last changed, as an ISO date. */
+  modified?: string;
+  children?: Entry[];
+}
+
+/** What the site calls it. */
+export function memoryLabel(agent: Agent): string {
+  return agent.memory.label || "Memory";
+}
+
+/**
+ * Beside the state folder rather than inside the memory it records. For most
+ * agents the memory IS their state folder, and a log inside the folder it logs
+ * would show up in its own tree and change it every time it was read.
+ */
+function logFor(agent: Agent): string {
+  return `${STATE}/memory-audit/${agent.name}.jsonl`;
+}
+
+function folder(agent: Agent): string {
+  return agent.memory.folder;
+}
+
+/**
+ * One line in the audit log. Awaited rather than left to finish on its own:
+ * the read that follows it must not happen if this could not be written.
+ */
+export async function record(
+  agent: Agent,
+  what: "read" | "write" | "list" | "serve" | "rename" | "delete" | "commit" | "push" | "pull",
+  path: string,
+  from: string,
+  extra: Record<string, unknown> = {},
+): Promise<void> {
+  await mkdir(`${STATE}/memory-audit`, { recursive: true });
+  await appendFile(logFor(agent), JSON.stringify({ at: new Date().toISOString(), what, path, from, ...extra }) + "\n");
+}
+
+/**
+ * The whole folder as a tree. An agent that has never written anything has no
+ * folder yet, which is an empty memory and not an error.
+ *
+ * Recorded like a read is. A listing carries no file contents, but the names in
+ * a folder of personal writing say plenty on their own.
+ */
+export async function memoryTree(agent: Agent, from = "unknown"): Promise<Entry[]> {
+  if (!existsSync(folder(agent))) return [];
+  await record(agent, "list", "/", from);
+  return walk(agent, "");
+}
+
+async function walk(agent: Agent, path: string, depth = 0): Promise<Entry[]> {
+  const { entries } = await list(folder(agent), path || undefined);
+  const out: Entry[] = [];
+  for (const entry of entries) {
+    const dir = entry.endsWith("/");
+    const name = dir ? entry.slice(0, -1) : entry;
+    // Left out rather than shown: a folder like secrets/ could never be opened
+    // from here, and trying to list it would stop the whole tree at the first
+    // one it met.
+    if (JUNK.includes(name) || unreachable(name)) continue;
+    const at = path ? `${path}/${name}` : name;
+    const about = await stat(`${folder(agent)}/${at}`).catch(() => null);
+    out.push({
+      name,
+      path: at,
+      dir,
+      size: dir ? undefined : about?.size,
+      modified: about?.mtime.toISOString(),
+      children: dir && depth < DEPTH ? await walk(agent, at, depth + 1) : undefined,
+    });
+  }
+  return out.sort((a, b) => Number(b.dir) - Number(a.dir) || a.name.localeCompare(b.name));
+}
+
+/**
+ * Where a caller's path lands, or null when it is not inside the folder.
+ *
+ * A path that tries to leave is answered the same way as a file that is not
+ * there, so whoever sent it learns nothing, and in particular not where on disk
+ * the folder is. Worth one line in the log, because somebody sent it on purpose.
+ */
+function inside(agent: Agent, path: string, from: string): string | null {
+  if (!existsSync(folder(agent))) return null;
+  try {
+    return confine(folder(agent), path);
+  } catch (error) {
+    console.error(`memory: ${agent.name} refused ${JSON.stringify(path)} from ${from}: ${(error as Error).message}`);
+    return null;
+  }
+}
+
+/** One file as text, for editing. A folder answers with what is in it. */
+export async function memoryOpen(agent: Agent, path: string, from: string) {
+  const resolved = inside(agent, path, from);
+  if (!resolved || !existsSync(resolved)) return null;
+  if (statSync(resolved).isDirectory()) {
+    await record(agent, "list", path, from);
+    return { path, dir: true as const, entries: await walk(agent, path) };
+  }
+  const file = await read(folder(agent), path);
+  // After the read and before the reply, so nothing is handed over unrecorded.
+  await record(agent, "read", path, from, { bytes: file.bytes });
+  return { path, dir: false as const, content: file.content, bytes: file.bytes };
+}
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".woff2": "font/woff2",
+};
+
+/**
+ * One file as its own bytes, for the frame it is shown in and whatever it
+ * links. Null when it is not there or not inside the folder.
+ *
+ * An HTML file has its root-relative links pointed back into this memory,
+ * under the same pass, because that is where they mean. A note that says
+ * `<link href="/static/style.css">` means the stylesheet at the top of its own
+ * folder, not one at the top of this website. Only an href or a src that
+ * starts with a single slash is touched: `//host` is somewhere else entirely.
+ */
+export async function memoryRaw(
+  agent: Agent,
+  path: string,
+  from: string,
+  under: string,
+): Promise<{ body: Buffer; type: string } | null> {
+  const resolved = inside(agent, path, from);
+  if (!resolved || !existsSync(resolved) || (await stat(resolved)).isDirectory()) return null;
+  const type = TYPES[extname(resolved).toLowerCase()] ?? "application/octet-stream";
+  let body = await readFile(resolved);
+  if (type.startsWith("text/html")) {
+    const html = body.toString("utf8").replace(/(\s(?:href|src)=["'])\/(?!\/)/gi, `$1${under}/`);
+    body = Buffer.from(withHead(html, noteHead()));
+  }
+  await record(agent, "serve", path, from, { bytes: body.length });
+  return { body, type };
+}
+
+/**
+ * An HTML file with `head` put first inside its own head, or where the browser
+ * will build one when it has none. Nothing the file wrote is changed, and what
+ * is added comes before it, so the file's own styles still win.
+ */
+export function withHead(html: string, head: string): string {
+  if (!head) return html;
+  // The lookahead matters: `<head[^>]*>` alone also matches `<header>`.
+  const open = /<head(?=[\s>])[^>]*>/i;
+  if (open.test(html)) return html.replace(open, (tag) => `${tag}\n${head}`);
+  const root = /<html(?=[\s>])[^>]*>/i;
+  if (root.test(html)) return html.replace(root, (tag) => `${tag}\n<head>${head}</head>`);
+  // After a doctype, never before it, or the page renders in quirks mode.
+  const doctype = /^\s*<!doctype[^>]*>/i;
+  if (doctype.test(html)) return html.replace(doctype, (tag) => `${tag}\n${head}`);
+  return `${head}\n${html}`;
+}
+
+export async function memorySave(agent: Agent, path: string, content: string, from: string) {
+  if (!inside(agent, path, from)) throw new BadRequest(`${path} is not somewhere in this memory.`);
+  const commit = Boolean(agent.memory.commit) && (await isRepo(agent));
+  const written = await write(folder(agent), path, content, {
+    commit,
+    message: commit ? `memory: ${path} from the site` : undefined,
+  });
+  await record(agent, "write", path, from, { bytes: content.length });
+  return { path, bytes: written.bytes };
+}
+
+/** Moves a file or a folder. Both ends have to be inside, and the new one must not exist. */
+export async function memoryRename(agent: Agent, from: string, to: string, who: string) {
+  const here = inside(agent, from, who);
+  const there = inside(agent, to, who);
+  if (!here || !there || !existsSync(here)) throw new BadRequest(`${from} is not somewhere in this memory.`);
+  if (existsSync(there)) throw new BadRequest(`${to} is already there.`);
+  await mkdir(dirname(there), { recursive: true });
+  await move(here, there);
+  await record(agent, "rename", from, who, { to });
+  return { from, to };
+}
+
+/**
+ * Deletes a file or a folder. In a repo that is recoverable from git, which is
+ * why the memory of an agent that keeps a person's notes should be one.
+ */
+export async function memoryDelete(agent: Agent, path: string, who: string) {
+  const here = inside(agent, path, who);
+  if (!here || !existsSync(here) || here === folder(agent)) {
+    throw new BadRequest(`${path} is not something in this memory that can be deleted.`);
+  }
+  await rm(here, { recursive: true });
+  await record(agent, "delete", path, who);
+  return { deleted: path };
+}
+
+/** That agent's audit log, newest first. */
+export async function memoryLog(agent: Agent, limit = 200): Promise<unknown[]> {
+  const text = await readFile(logFor(agent), "utf8").catch(() => "");
+  return text
+    .split("\n")
+    .filter(Boolean)
+    .slice(-limit)
+    .reverse()
+    .map((line) => {
+      try {
+        return JSON.parse(line) as unknown;
+      } catch {
+        return { at: "", what: "unreadable", line };
+      }
+    });
+}
+
+// Source control, when the memory is a repo. Enough to mirror the panel an
+// editor puts beside its file tree: what changed, commit it, push, pull, and the
+// recent history. Every call is `git` with an argument array and never a shell
+// string, and nothing here takes a path from the browser: a commit is the whole
+// tree, which is the only shape of commit this offers.
+
+async function inRepo(agent: Agent, ...args: string[]): Promise<string> {
+  const { stdout } = await git("git", args, { cwd: folder(agent), maxBuffer: 8 << 20, timeout: 60_000 });
+  return stdout;
+}
+
+/**
+ * Whether this memory is itself a git repository: its folder is the top of one.
+ *
+ * Being inside one is not enough, and that difference is the whole of this
+ * function. An agent's memory defaults to its folder under the state
+ * directory, and that is usually inside the repo the agents are written in.
+ * Asked from there, git walks up and answers for that repo: its branch, its
+ * changes, and a "commit all" that stages every file in it from wherever it is
+ * run. So a memory panel would show somebody's unrelated work in progress as
+ * the memory's own changes, one click would commit it under a message written
+ * about something else, and push would send it off the box.
+ */
+async function isRepo(agent: Agent): Promise<boolean> {
+  if (!existsSync(folder(agent))) return false;
+  try {
+    const top = (await inRepo(agent, "rev-parse", "--show-toplevel")).trim();
+    return realpathSync(top) === realpathSync(folder(agent));
+  } catch {
+    return false;
+  }
+}
+
+export async function memoryGit(agent: Agent) {
+  if (!(await isRepo(agent))) return { repo: false as const };
+  const [porcelain, branch, history] = await Promise.all([
+    inRepo(agent, "status", "--porcelain=v1"),
+    inRepo(agent, "rev-parse", "--abbrev-ref", "HEAD").catch(() => "HEAD\n"),
+    inRepo(agent, "log", "-20", "--date=short", "--format=%h%x00%ad%x00%an%x00%s").catch(() => ""),
+  ]);
+  const changes = porcelain
+    .split("\n")
+    .filter((line) => line.trim())
+    // XY<space>path, where XY is the two-letter index and worktree status.
+    .map((line) => ({ status: line.slice(0, 2).trim() || "?", path: line.slice(3) }));
+  let ahead = 0;
+  let behind = 0;
+  let upstream: string | null = null;
+  try {
+    upstream = (await inRepo(agent, "rev-parse", "--abbrev-ref", "@{upstream}")).trim();
+    const [a, b] = (await inRepo(agent, "rev-list", "--left-right", "--count", "HEAD...@{upstream}"))
+      .trim()
+      .split(/\s+/)
+      .map(Number);
+    ahead = a || 0;
+    behind = b || 0;
+  } catch {
+    // No upstream. Push says so rather than guessing one.
+  }
+  const log = history
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [sha, date, author, subject] = line.split("\0");
+      return { sha, date, author, subject };
+    });
+  return { repo: true as const, branch: branch.trim(), changes, ahead, behind, upstream, log };
+}
+
+export async function memoryCommit(agent: Agent, message: string, who: string) {
+  const text = message.trim();
+  if (!text) throw new BadRequest("Write a commit message first.");
+  if (!(await isRepo(agent))) throw new BadRequest("This memory is not a git repository.");
+  await inRepo(agent, "add", "-A");
+  const staged = (await inRepo(agent, "diff", "--cached", "--name-only")).trim();
+  if (!staged) throw new BadRequest("Nothing to commit.");
+  await inRepo(agent, "commit", "-m", text);
+  const sha = (await inRepo(agent, "rev-parse", "--short", "HEAD")).trim();
+  await record(agent, "commit", "/", who, { commit: sha, message: text });
+  return { commit: sha, files: staged.split("\n").length };
+}
+
+/**
+ * Push is the one thing here that sends these files off the box, so it says
+ * where they went rather than just that it worked.
+ */
+export async function memoryPush(agent: Agent, who: string) {
+  const status = await memoryGit(agent);
+  if (!status.repo) throw new BadRequest("This memory is not a git repository.");
+  if (!status.upstream) throw new BadRequest("No upstream branch is set for this branch.");
+  if (!status.ahead) return { pushed: 0, upstream: status.upstream };
+  const url = (await inRepo(agent, "remote", "get-url", status.upstream.split("/")[0]).catch(() => "")).trim();
+  await inRepo(agent, "push");
+  await record(agent, "push", "/", who, { upstream: status.upstream, url, commits: status.ahead });
+  return { pushed: status.ahead, upstream: status.upstream, url };
+}
+
+/** Fast-forward only: a merge or a conflict is not something a button can sensibly resolve. */
+export async function memoryPull(agent: Agent, who: string) {
+  if (!(await isRepo(agent))) throw new BadRequest("This memory is not a git repository.");
+  const out = await inRepo(agent, "pull", "--ff-only").catch((error: { stderr?: string; message: string }) => {
+    throw new BadRequest(String(error.stderr || error.message).split("\n")[0]);
+  });
+  await record(agent, "pull", "/", who);
+  return { output: out.trim() };
+}