@chloejs/core 0.2.0

package/serve/page.ts

@@ -0,0 +1,142 @@
+// Finding a better page than the built-in one, if the repo installed a package
+// that offers it.
+//
+// The runtime does not know @chloejs/ui exists. It knows a convention: any
+// installed package whose package.json has a "chloePage" naming a folder with
+// an index.html in it is offering a page, and the first one found is served
+// instead of site.ts's. That is what makes `npm install @chloejs/ui` upgrade the
+// site with nothing configured, and what lets somebody else's dashboard take
+// its place the same way.
+//
+// Looked for once, at startup. A package installed while the process is running
+// is not picked up until it restarts, which is the same as every other
+// dependency.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join, resolve, sep } from "node:path";
+import { readFile } from "node:fs/promises";
+import type { ServerResponse } from "node:http";
+
+import { ROOT } from "#chloe/core/paths.ts";
+
+export interface Page {
+  /** The package that offered it, for saying so at startup. */
+  name: string;
+  /** The folder its index.html is in. */
+  dir: string;
+}
+
+const TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".map": "application/json; charset=utf-8",
+  ".webmanifest": "application/manifest+json",
+};
+
+let scanned: Page | null | undefined;
+
+/**
+ * The installed page, or null when there is none. node_modules is walked once
+ * and the answer kept.
+ *
+ * CHLOE_PAGE=builtin ignores whatever is installed and serves the runtime's
+ * own site instead. That is how you tell a broken dashboard from a broken
+ * runtime without uninstalling anything.
+ */
+export function installedPage(): Page | null {
+  if (process.env.CHLOE_PAGE === "builtin") return null;
+  if (scanned === undefined) scanned = pageIn(`${ROOT}/node_modules`);
+  return scanned;
+}
+
+/** The first package in a node_modules folder that offers a page, or null. */
+export function pageIn(modules: string): Page | null {
+  if (!existsSync(modules)) return null;
+  for (const entry of readdirSync(modules, { withFileTypes: true })) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name.startsWith(".")) continue;
+    // A scope holds packages rather than being one.
+    const packages = entry.name.startsWith("@")
+      ? readdirSync(`${modules}/${entry.name}`).map((one) => `${entry.name}/${one}`)
+      : [entry.name];
+    for (const name of packages) {
+      const offered = offers(`${modules}/${name}`);
+      if (offered) return { name, dir: offered };
+    }
+  }
+  return null;
+}
+
+let head: string | undefined;
+
+/**
+ * What the installed page wants at the top of every HTML file shown from a
+ * memory: the contents of `note-head.html` in its folder, or "" when it has
+ * none. Its links should be root-relative, like `/notes.css`, since the page's
+ * own files are served at the root. Read once, like the page itself.
+ */
+export function noteHead(): string {
+  if (head !== undefined) return head;
+  const page = installedPage();
+  const file = page ? `${page.dir}/note-head.html` : "";
+  head = file && existsSync(file) ? readFileSync(file, "utf8").trim() : "";
+  return head;
+}
+
+/** The folder a package offers as a page, if it offers one and it is really there. */
+function offers(dir: string): string | null {
+  let declared: unknown;
+  try {
+    declared = (JSON.parse(readFileSync(`${dir}/package.json`, "utf8")) as { chloePage?: unknown }).chloePage;
+  } catch {
+    return null;
+  }
+  if (typeof declared !== "string" || !declared) return null;
+  const at = resolve(dir, declared);
+  // A package that says it has a page but has not been built yet is not an
+  // error worth stopping for: the built-in page is still there.
+  if (!existsSync(`${at}/index.html`)) {
+    console.error(`${dir} offers a page at ${declared}, but there is no index.html in it. Has it been built?`);
+    return null;
+  }
+  return at;
+}
+
+/**
+ * Serves one file out of the page's folder, or the page itself.
+ *
+ * A file that is there is that file. Anything else is one of the page's own
+ * addresses, so it gets index.html and the browser works out which view it is.
+ * That is a proxy's `try_files {path} /index.html`.
+ *
+ * It used to decide by whether the address had a dot in it, which is right for
+ * /page.js and wrong for /agents/chloe/memory/notes/curriculum.html: an address
+ * inside the page can name a file somewhere else, and a dot in it is not a
+ * reason to go looking for that file here. Every deep link to a memory file was
+ * a 404.
+ */
+export async function servePageFile(response: ServerResponse, page: Page, path: string): Promise<boolean> {
+  const asked = path.includes(".") ? inside(page.dir, path) : null;
+  const found = asked && existsSync(asked) && statSync(asked).isFile() ? asked : `${page.dir}/index.html`;
+  try {
+    const body = await readFile(found);
+    response.writeHead(200, { "content-type": TYPES[extname(found)] ?? "application/octet-stream" });
+    response.end(body);
+  } catch {
+    response.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Not here.\n");
+  }
+  return true;
+}
+
+/** Keeps a browser's path inside the page's folder. */
+function inside(dir: string, path: string): string | null {
+  const at = resolve(join(dir, path));
+  return at === dir || at.startsWith(dir + sep) ? at : null;
+}

package/serve/pass.ts

@@ -0,0 +1,45 @@
+// A pass to read one agent's memory, carried in the address rather than in a
+// cookie, for the frame a memory file is shown in.
+//
+// Why not the cookie. A memory file is somebody's own HTML, and every one of
+// them runs its own script. So it is served sandboxed (see memory.ts), which
+// gives the document an origin of its own that is nobody's: its scripts run,
+// but they cannot reach the page around them or call the API as the person
+// signed in. That is the whole point. It also means the browser will not send
+// the session cookie for the stylesheet and the script the file links, because
+// that origin is not this site. So those need another way to show they may be
+// served, and a pass in the path is it: the file's own relative and
+// root-relative links resolve under the pass and carry it with them.
+//
+// What a pass can do is exactly what a frame needs and nothing else: read files
+// in one agent's memory, for ten minutes. It cannot write, cannot reach another
+// agent's memory, cannot make a token or talk to an agent. A script in a note
+// can read the pass from its own address, which is fine: it is already running
+// inside that agent's memory, and connect-src 'none' stops it sending the pass
+// anywhere.
+import { seal, unseal } from "./login.ts";
+
+/** Long enough to load a frame and everything it links, short enough to be worthless later. */
+const LASTS = 10 * 60;
+
+const PURPOSE = "memory-pass";
+
+interface Payload {
+  /** Whose memory. */
+  a: string;
+  /** Until when, in seconds since the epoch. */
+  u: number;
+}
+
+/** A pass to read that agent's memory. */
+export function makePass(agent: string): string {
+  return seal(PURPOSE, { a: agent, u: Math.floor(Date.now() / 1000) + LASTS } satisfies Payload);
+}
+
+/** Which agent's memory this pass reads, or null when it is not a live pass. */
+export function checkPass(value: string): string | null {
+  const payload = unseal<Payload>(PURPOSE, value);
+  if (!payload || typeof payload.a !== "string" || typeof payload.u !== "number") return null;
+  if (payload.u <= Math.floor(Date.now() / 1000)) return null;
+  return payload.a;
+}

package/serve/recentWork.ts

@@ -0,0 +1,69 @@
+// What each agent did recently, for the overview. The same job run again and
+// again is one line with a count, or a check every quarter hour would be all
+// there is to see.
+import { db } from "#chloe/core/db.ts";
+import type { Agent } from "#chloe/load/load.ts";
+
+export interface RecentWork {
+  /** The newest run of the group, which is the one a click opens. */
+  id: string;
+  /** The channel it came in on, like "schedule" or "telegram". */
+  source: string;
+  /** The job it was, or null for a turn somebody started by talking to it. */
+  job: string | null;
+  started: string;
+  finished: string | null;
+  summary: string | null;
+  error: string | null;
+  /** How many runs in a row this line stands for, and how many of them failed. */
+  times: number;
+  failed: number;
+  cost: number;
+}
+
+/** Far enough back to find a few different things behind a busy job. */
+const LOOK_BACK = 200;
+
+interface Row {
+  id: string;
+  source: string;
+  job: string | null;
+  started: string;
+  finished: string | null;
+  summary: string | null;
+  error: string | null;
+  cost: number;
+}
+
+export function recentWork(agent: Agent, count = 3): RecentWork[] {
+  const rows = db
+    .prepare(
+      "select id, source, job, started, finished, summary, error, cost from runs where agent = ? order by started desc limit ?",
+    )
+    .all(agent.name, LOOK_BACK) as unknown as Row[];
+
+  const out: RecentWork[] = [];
+  for (const run of rows) {
+    const last = out[out.length - 1];
+    if (last && last.source === run.source && last.job === run.job) {
+      last.times++;
+      last.failed += run.error ? 1 : 0;
+      last.cost += Number(run.cost ?? 0);
+      continue;
+    }
+    if (out.length === count) break;
+    out.push({
+      id: run.id,
+      source: run.source,
+      job: run.job,
+      started: run.started,
+      finished: run.finished,
+      summary: run.summary,
+      error: run.error,
+      times: 1,
+      failed: run.error ? 1 : 0,
+      cost: Number(run.cost ?? 0),
+    });
+  }
+  return out;
+}

package/serve/site.ts

@@ -0,0 +1,409 @@
+// The runtime's own site: which agents are loaded, what each one is configured
+// to do, the API docs, the tokens, and the notes folder if one is configured.
+//
+// Plain HTML written by hand, with no build step and no dependencies, because
+// a build step in the runtime is the thing this site exists to avoid. It is
+// deliberately basic. A package that offers a better page takes over every
+// address here except the docs: see page.ts.
+//
+// Server rendered, so the only script on the page is the few lines a form
+// needs. Everything it shows, it was given.
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { hasChannel, type Agent } from "#chloe/load/load.ts";
+import { caller, from, hasAccount } from "./login.ts";
+import { installedPage, servePageFile } from "./page.ts";
+import { memoryLabel, memoryTree } from "./memory.ts";
+import { makePass } from "./pass.ts";
+import { describe } from "#chloe/timer/every.ts";
+
+/** What the docs page needs to know about a route. http.ts's Route is this plus its handler. */
+export interface RouteDoc {
+  method: string;
+  path: string;
+  does: string;
+  takes?: string;
+  open?: boolean;
+  token?: boolean;
+  needsApiChannel?: boolean;
+}
+
+interface Context {
+  agent(name: string): Agent;
+  agents(): Map<string, Agent>;
+}
+
+/**
+ * Everything that is not /api. The installed page gets first refusal, and the
+ * built-in one answers when there is none.
+ */
+export async function sitePage(
+  request: IncomingMessage,
+  response: ServerResponse,
+  path: string,
+  context: Context,
+): Promise<void> {
+  const page = installedPage();
+  if (page) return void (await servePageFile(response, page, path));
+
+  const who = caller(request);
+  // The site is the account's. A token is for the API, and giving it a browser
+  // session would quietly widen what it can reach.
+  if (!who || who.kind !== "account") {
+    if (path === "/login") return send(response, loginPage());
+    return away(response, "/login");
+  }
+  if (path === "/login") return away(response, "/");
+
+  const parts = path.split("/").filter(Boolean).map(decodeURIComponent);
+
+  if (path === "/") return send(response, homePage(context));
+  if (parts[0] === "agents" && parts[1] && parts.length === 2) {
+    return send(response, agentPage(context.agent(parts[1]), context));
+  }
+  if (path === "/tokens") return send(response, tokensPage(context));
+  // One agent's memory lives under that agent, the same as everything else of its.
+  if (parts[0] === "agents" && parts[1] && parts[2] === "memory") {
+    return send(response, await memoryPage(context.agent(parts[1]), parts.slice(3).join("/"), from(request)));
+  }
+  send(response, shell("Not here", `<h1>Not here</h1><p>No page at <code>${esc(path)}</code>.</p>`), 404);
+}
+
+function send(response: ServerResponse, body: string, status = 200): void {
+  response.writeHead(status, { "content-type": "text/html; charset=utf-8" });
+  response.end(body);
+}
+
+function away(response: ServerResponse, to: string): void {
+  response.writeHead(303, { location: to });
+  response.end();
+}
+
+function esc(value: unknown): string {
+  return String(value ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+const STYLE = `
+:root { color-scheme: light dark; --ink:#1b1a18; --paper:#fbfaf8; --quiet:#6b6862; --line:#e4e0d9; --link:#1f5f8b; }
+@media (prefers-color-scheme: dark) {
+  :root { --ink:#e8e5df; --paper:#171614; --quiet:#948f86; --line:#2e2c28; --link:#7fb5d8; }
+}
+* { box-sizing: border-box; }
+body { margin:0; padding:2rem 1rem 4rem; background:var(--paper); color:var(--ink);
+  font:16px/1.55 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width: 52rem; margin: 0 auto; }
+h1 { font-size:1.5rem; margin:0 0 .25rem; }
+h2 { font-size:1.05rem; margin:2rem 0 .5rem; }
+h3 { font-size:.95rem; margin:1.25rem 0 .35rem; }
+a { color:var(--link); }
+code, pre { font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; font-size:.875em; }
+pre { background:color-mix(in srgb, var(--ink) 5%, transparent); padding:.75rem; border-radius:6px; overflow:auto; }
+nav { display:flex; gap:1rem; flex-wrap:wrap; margin:0 0 2rem; padding-bottom:.75rem; border-bottom:1px solid var(--line); }
+nav a { text-decoration:none; }
+.quiet { color:var(--quiet); }
+.card { border:1px solid var(--line); border-radius:8px; padding:1rem; margin:.75rem 0; }
+.card h3 { margin-top:0; }
+table { border-collapse:collapse; width:100%; margin:.5rem 0 1rem; }
+th, td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--line); vertical-align:top; }
+th { font-weight:600; font-size:.8rem; color:var(--quiet); text-transform:uppercase; letter-spacing:.04em; }
+form { display:flex; gap:.5rem; flex-wrap:wrap; align-items:center; margin:.75rem 0; }
+input, button { font:inherit; padding:.45rem .6rem; border:1px solid var(--line); border-radius:6px;
+  background:var(--paper); color:var(--ink); }
+button { cursor:pointer; background:color-mix(in srgb, var(--ink) 8%, transparent); }
+.tag { font-size:.75rem; padding:.1rem .4rem; border-radius:4px; border:1px solid var(--line); color:var(--quiet); }
+ul.tree { list-style:none; padding-left:1rem; margin:.25rem 0; }
+iframe { width:100%; height:32rem; border:1px solid var(--line); border-radius:6px; background:var(--paper); }
+`;
+
+/**
+ * Chloe's colours as a data URI, rather than a file and a route to serve it.
+ * A browser asks for /favicon.ico on every page whether one is offered or not,
+ * and an unanswered one is a 404 in the console of every page this site has.
+ */
+const ICON =
+  `<link rel="icon" href="data:image/svg+xml,` +
+  `%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E` +
+  `%3Crect width='32' height='32' rx='8' fill='%231d473b'/%3E` +
+  `%3Ccircle cx='16' cy='16' r='6' fill='%23f4efe1'/%3E%3C/svg%3E">`;
+
+function shell(title: string, body: string, nav = true): string {
+  return `<!doctype html>
+<html lang="en"><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+${ICON}
+<style>${STYLE}</style>
+<main>
+${nav ? `<nav>
+  <a href="/">Agents</a>
+  <a href="/api">API</a>
+  <a href="/tokens">Tokens</a>
+  <a href="#" onclick="fetch('/api/logout',{method:'POST'}).then(()=>location='/login');return false">Sign out</a>
+</nav>` : ""}
+${body}
+</main>
+</html>`;
+}
+
+function loginPage(): string {
+  const making = !hasAccount();
+  return shell(
+    making ? "Make the account" : "Sign in",
+    `<h1>${making ? "Make the account" : "Sign in"}</h1>
+<p class="quiet">${
+      making
+        ? "This copy has no account yet. The first one is made here, or with <code>npm run account</code> on the box."
+        : "One account. Everything behind it is the agents, what they have run, and whatever folders they keep."
+    }</p>
+<form onsubmit="return go(this)">
+  <input name="username" placeholder="Username" autocomplete="username" required>
+  <input name="password" type="password" placeholder="Password" autocomplete="current-password" required>
+  <button>${making ? "Make it" : "Sign in"}</button>
+</form>
+<p id="trouble" class="quiet"></p>
+<script>
+function go(form) {
+  fetch(${making ? "'/api/setup'" : "'/api/login'"}, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ username: form.username.value, password: form.password.value }),
+  })
+    .then((r) => r.json())
+    .then((a) => { if (a.ok) location = '/'; else document.getElementById('trouble').textContent = a.error; })
+    .catch((e) => { document.getElementById('trouble').textContent = String(e); });
+  return false;
+}
+</script>`,
+    false,
+  );
+}
+
+function homePage(context: Context): string {
+  const agents = [...context.agents().values()];
+  const body = `<h1>Chloe</h1>
+<p class="quiet">${agents.length} agent${agents.length === 1 ? "" : "s"} loaded. This is the runtime's own site.
+Install a package that offers a page and it takes over from here.</p>
+
+${agents
+  .map(
+    (agent) => `<div class="card">
+  <h3><a href="/agents/${esc(agent.name)}">${esc(agent.label || agent.name)}</a>
+    ${hasChannel(agent, "api") ? '<span class="tag">on the api</span>' : ""}</h3>
+  <p class="quiet">${esc(agent.description || "No description.")}</p>
+  <p class="quiet"><code>${esc(agent.model)}</code> &middot; ${agent.jobs.length} job${
+      agent.jobs.length === 1 ? "" : "s"
+    } &middot; ${agent.skills.length} skill${agent.skills.length === 1 ? "" : "s"}
+    &middot; <a href="/agents/${esc(agent.name)}/memory">${esc(memoryLabel(agent))}</a></p>
+</div>`,
+  )
+  .join("\n")}
+
+<h2>Where things are</h2>
+<table>
+  <tr><th>The API</th><td><a href="/api">/api</a> lists every route it answers.</td></tr>
+  <tr><th>Tokens</th><td><a href="/tokens">/tokens</a> makes and revokes them, for other systems.</td></tr>
+</table>`;
+  return shell("Chloe", body);
+}
+
+function agentPage(agent: Agent, context: Context): string {
+  const body = `<h1>${esc(agent.label || agent.name)}</h1>
+<p class="quiet">${esc(agent.description || "No description.")}</p>
+<p class="quiet">This page is read only. Its folder is on disk, and an edit there is live in under a second.</p>
+
+<table>
+  <tr><th>Name</th><td><code>${esc(agent.name)}</code></td></tr>
+  <tr><th>Model</th><td><code>${esc(agent.model)}</code></td></tr>
+  <tr><th>Channels</th><td>${
+    agent.channels.length
+      ? agent.channels.map((one) => one.name).sort().map((one) => `<code>${esc(one)}</code>`).join(", ")
+      : '<span class="quiet">none</span>'
+  }</td></tr>
+  <tr><th>Tools</th><td>${
+    Object.keys(agent.tools ?? {}).length
+      ? Object.keys(agent.tools ?? {}).sort().map((one) => `<code>${esc(one)}</code>`).join(", ")
+      : '<span class="quiet">none</span>'
+  }</td></tr>
+  <tr><th>Skills</th><td>${
+    agent.skills.length
+      ? agent.skills.map((one) => `<code>${esc(one.name)}</code>`).join(", ")
+      : '<span class="quiet">none</span>'
+  }</td></tr>
+</table>
+
+<h2>Jobs</h2>
+${
+  agent.jobs.length
+    ? `<table>
+<tr><th>Job</th><th>When</th><th>How</th><th>What it does</th></tr>
+${agent.jobs
+  .map(
+    (job) => `<tr>
+  <td><code>${esc(job.id)}</code></td>
+  <td>${job.cron ? esc(describe(job.cron, job.timezone)) : '<span class="quiet">when started</span>'}</td>
+  <td>${job.run ? "code" : esc(job.model ?? agent.model)}</td>
+  <td class="quiet">${esc(job.description ?? "")}</td>
+</tr>`,
+  )
+  .join("\n")}
+</table>`
+    : '<p class="quiet">No jobs.</p>'
+}
+
+<h2>Reaching it</h2>
+${
+  hasChannel(agent, "api")
+    ? `<p>It binds an api channel, so a token may talk to it and run its jobs.</p>
+<pre>curl -X POST http://127.0.0.1:3067/api/agents/${esc(agent.name)}/chat \\
+  -H "authorization: Bearer $CHLOE_TOKEN" \\
+  -H "content-type: application/json" \\
+  -d '{"prompt":"what is late?"}'</pre>`
+    : `<p class="quiet">It has no api channel, so only a signed-in account can talk to it.
+Add <code>apiChannel()</code> to the channels in its definition to open it to a token.</p>`
+}`;
+  return shell(agent.label || agent.name, body);
+}
+
+function tokensPage(context: Context): string {
+  const body = `<h1>Tokens</h1>
+<p class="quiet">For another system to read this API and reach the agents that bind an api channel.
+A token cannot write files, make tokens or revoke them. The secret is shown once and is not stored.</p>
+
+<form onsubmit="return make(this)">
+  <input name="name" placeholder="What is it for" required>
+  <button>Make one</button>
+</form>
+<pre id="made" hidden></pre>
+
+<table id="list"><tr><th>Name</th><th>Made</th><th>Last used</th><th></th></tr></table>
+
+<script>
+function draw(tokens) {
+  const rows = tokens.map((t) => {
+    const when = t.revoked
+      ? '<span class="quiet">revoked ' + t.revoked.slice(0, 10) + '</span>'
+      : '<button onclick="revoke(\\'' + t.id + '\\')">Revoke</button>';
+    return '<tr><td>' + t.name + '</td><td class="quiet">' + t.created.slice(0, 10) + '</td><td class="quiet">' +
+      (t.lastUsed ? t.lastUsed.slice(0, 16).replace('T', ' ') : 'never') + '</td><td>' + when + '</td></tr>';
+  });
+  document.getElementById('list').innerHTML =
+    '<tr><th>Name</th><th>Made</th><th>Last used</th><th></th></tr>' + rows.join('');
+}
+function load() { fetch('/api/tokens').then((r) => r.json()).then(draw); }
+function make(form) {
+  fetch('/api/tokens', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: form.name.value }),
+  })
+    .then((r) => r.json())
+    .then((t) => {
+      const shown = document.getElementById('made');
+      shown.hidden = false;
+      shown.textContent = t.secret
+        ? t.name + '\\n\\n' + t.secret + '\\n\\nCopy it now. It is not stored and cannot be shown again.'
+        : t.error;
+      form.reset();
+      load();
+    });
+  return false;
+}
+function revoke(id) {
+  fetch('/api/tokens/' + id + '/revoke', { method: 'POST' }).then(load);
+}
+load();
+</script>`;
+  return shell("Tokens", body);
+}
+
+async function memoryPage(agent: Agent, path: string, at: string): Promise<string> {
+  const label = memoryLabel(agent);
+  const here = `/agents/${agent.name}/memory`;
+
+  if (!path) {
+    const tree = await memoryTree(agent, at);
+    return shell(
+      `${agent.name}: ${label}`,
+      `<h1>${esc(agent.label || agent.name)}&rsquo;s ${esc(label.toLowerCase())}</h1>
+<p class="quiet"><code>${esc(agent.memory.folder)}</code>. Every file opened here is written to the audit log,
+which reading the same file from a shell is not. That difference is deliberate.</p>
+${drawTree(here, tree)}`,
+    );
+  }
+
+  // In a frame, under a pass, sandboxed. See pass.ts and framed() in http.ts:
+  // the file runs its own script and cannot reach this page or the API.
+  const src = `/memory/${encodeURIComponent(makePass(agent.name))}/${path.split("/").map(encodeURIComponent).join("/")}`;
+  return shell(
+    path,
+    `<p class="quiet"><a href="${esc(here)}">${esc(label)}</a> / ${esc(path)}</p>
+<iframe src="${esc(src)}" sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox" title="${esc(path)}"></iframe>`,
+  );
+}
+
+function drawTree(here: string, entries: { name: string; path: string; dir: boolean; children?: unknown }[]): string {
+  if (!entries.length) return '<p class="quiet">Nothing here.</p>';
+  return `<ul class="tree">${entries
+    .map(
+      (one) =>
+        `<li>${one.dir ? `<span class="quiet">${esc(one.name)}/</span>` : `<a href="${esc(here)}/${esc(one.path)}">${esc(one.name)}</a>`}${
+          one.dir && Array.isArray(one.children) && one.children.length
+            ? drawTree(here, one.children as { name: string; path: string; dir: boolean }[])
+            : ""
+        }</li>`,
+    )
+    .join("")}</ul>`;
+}
+
+/** The API docs, generated from the same list the router dispatches on. */
+export function docsPage(routes: RouteDoc[]): string {
+  const groups: [string, (one: RouteDoc) => boolean][] = [
+    ["The ways in", (one) => Boolean(one.open)],
+    ["Reading", (one) => !one.open && Boolean(one.token) && one.method === "GET"],
+    ["Talking to an agent", (one) => Boolean(one.needsApiChannel)],
+    ["The account's own", (one) => !one.open && !one.token],
+  ];
+  const body = `<h1>The API</h1>
+<p class="quiet">Every route this runtime answers. It binds <code>127.0.0.1:3067</code> and is not meant to be
+put on a public name: reach it from another machine over a tunnel.</p>
+
+<h2>Who may call what</h2>
+<table>
+  <tr><th>anybody</th><td>The four ways in. Each says as little as it can.</td></tr>
+  <tr><th>account</th><td>Somebody signed in on this box, as the cookie or as
+    <code>Authorization: Bearer &lt;the value /api/login returned&gt;</code>. Can do everything.</td></tr>
+  <tr><th>token</th><td>Another system, as <code>Authorization: Bearer chloe_...</code>. Reading, plus chat and
+    jobs for the agents that bind an api channel. Never writing, and never the tokens themselves.
+    Made at <a href="/tokens">/tokens</a>.</td></tr>
+</table>
+
+${groups
+  .map(([title, pick]) => {
+    const found = routes.filter(pick);
+    if (!found.length) return "";
+    return `<h2>${esc(title)}</h2>
+<table>
+${found
+  .map(
+    (one) => `<tr>
+  <td><code>${esc(one.method)} ${esc(one.path)}</code>${
+      one.takes ? `<br><span class="quiet"><code>${esc(one.takes)}</code></span>` : ""
+    }</td>
+  <td>${esc(one.does)}</td>
+</tr>`,
+  )
+  .join("\n")}
+</table>`;
+  })
+  .join("\n")}
+
+<h2>From something that is not a browser</h2>
+<pre>curl http://127.0.0.1:3067/api/agents -H "authorization: Bearer $CHLOE_TOKEN"</pre>
+<p class="quiet">The same list as JSON is this page with no <code>Accept: text/html</code>:</p>
+<pre>curl http://127.0.0.1:3067/api</pre>`;
+  return shell("The API", body);
+}