@chloejs/core 0.2.1 → 0.2.3

package/README.md

@@ -1,5 +1,9 @@
 # Chloe
 
+[![npm](https://img.shields.io/npm/v/@chloejs/core)](https://www.npmjs.com/package/@chloejs/core)
+
+**[chloejs.org](https://chloejs.org)**: the docs, the examples and the reference.
+
 Chloe is a TypeScript agent framework that uses AI only when you need it.
 
 You write the workflow in code, **and ask AI where a step needs judgement**. You
@@ -198,16 +202,17 @@ serve/       the one port: every route, the login, tokens, the plain page
 core/        the floor. steps.ts runs a job, turn.ts runs a prompt, clock.ts
              starts each job when its cron line is due
 scorers/     how a run is marked
-do/          the work itself, called straight from a job
+services/    the work itself, called straight from a job, published as
+             "@chloejs/core/services"
 channels/    the ways in, for an agent to bind
 ops/         the tests, the evals, talking to an agent, making the account,
              and install.sh, which installs the service
 test-agent/  the agent the tests load. Not published
 ```
 
-Six entrances and no others: `@chloejs/core`, `@chloejs/core/tools`,
-`@chloejs/core/channels/<name>`, `@chloejs/core/scorers`, `@chloejs/core/timer` and
-`@chloejs/core/test`.
+Seven entrances and no others: `@chloejs/core`, `@chloejs/core/services`,
+`@chloejs/core/tools`, `@chloejs/core/channels`, `@chloejs/core/scorers`,
+`@chloejs/core/timer` and `@chloejs/core/test`.
 
 ## Use code when you know what to do. Use AI when you do not.
 

package/channels/api.ts

@@ -1,7 +1,7 @@
 // Opting one agent in to being reached by another system.
 //
 //   // agents/<name>/agent.ts
-//   import { apiChannel } from "@chloejs/core/channels/api";
+//   import { apiChannel } from "@chloejs/core/channels";
 //   channels: [apiChannel()],
 //
 // Binding it makes two routes answer for that agent when the caller holds a

package/channels/index.ts

@@ -0,0 +1,13 @@
+// The ways an agent is reached. Each is a function an agent calls in the
+// `channels` list of its agent.ts.
+//
+//   import { telegramChannel, apiChannel } from "@chloejs/core/channels";
+//
+// A channel chloe does not ship is written in the agent's own channels/
+// folder, and hands each message to `receive`. Same rule as `index.ts`:
+// adding a name here is publishing it.
+
+export { telegramChannel, type TelegramOptions } from "./telegram.ts";
+export { slackChannel, type SlackOptions } from "./slack.ts";
+export { apiChannel } from "./api.ts";
+export { receive, commands, type Incoming, type Rules, type While, type Handled } from "./shared.ts";

package/channels/shared.ts

@@ -4,7 +4,7 @@
 // here, once, so Telegram, the API and any channel written later behave the
 // same way. A channel written in an agent's own folder imports it too:
 //
-//   import { receive, type Incoming } from "@chloejs/core/channels/shared";
+//   import { receive, type Incoming } from "@chloejs/core/channels";
 //
 // In order, and the first that applies decides:
 //

package/channels/slack.ts

@@ -1,7 +1,7 @@
 // Talking to an agent from Slack. It is one entry in the agent's channels:
 //
 //   // agents/<name>/agent.ts
-//   import { slackChannel } from "@chloejs/core/channels/slack";
+//   import { slackChannel } from "@chloejs/core/channels";
 //   channels: [slackChannel({ allowFrom: ["U0123ABCD"] })],
 //
 // It needs a Slack app with Socket Mode on, which is chloe opening a

package/channels/telegram.ts

@@ -1,7 +1,7 @@
 // Talking to an agent from Telegram. It is one entry in the agent's channels:
 //
 //   // agents/<name>/agent.ts
-//   import { telegramChannel } from "@chloejs/core/channels/telegram";
+//   import { telegramChannel } from "@chloejs/core/channels";
 //   channels: [telegramChannel({ allowFrom: [111111111] })],
 //
 // The bot's token is TELEGRAM_BOT_TOKEN, or `credentials: { botToken }`. To

package/core/settings.ts

@@ -32,13 +32,13 @@ const schema = z.object({
       judge: z.string().default("anthropic/claude-sonnet-5"),
     })
     .prefault({}),
-  app: z
+  email: z
     .object({
-      /** Where an agent's mail goes. Comma separated for more than one. */
-      send_email_to: z.string().default(""),
+      /** Who carries an agent's mail. Its key is in that provider's own section. */
+      provider: z.enum(["resend"]).default("resend"),
     })
     .prefault({}),
-  /** Sending mail. */
+  /** Sending mail through Resend. */
   resend: z
     .object({
       /** The key an agent's mail is sent with. Without one, nothing is sent. */

package/index.ts

@@ -2,10 +2,12 @@
 //
 // Everything an agent, a job, a tool or a channel is written with is named
 // here, and nothing else in this folder is anybody's business. Import it as
-// "@chloejs/core": the three lines below say the rest.
+// "@chloejs/core": the lines below say the rest.
 //
 //   import { defineJob, tool, note } from "@chloejs/core";
-//   import { telegramChannel } from "@chloejs/core/channels/telegram";  // reaching an agent
+//   import { run, sendEmail } from "@chloejs/core/services";  // the work, for a job
+//   import { read_mail } from "@chloejs/core/tools";  // the work, for a model
+//   import { telegramChannel } from "@chloejs/core/channels";  // reaching an agent
 //   import { calls, expectations } from "@chloejs/core/scorers";  // marking a run
 //
 // Adding a name here is publishing it, and taking one away is a break, so this
@@ -38,15 +40,3 @@ export { readSettings, setting, settings, type Settings } from "./core/settings.
 export { confine } from "./core/confine.ts";
 export { note, type Note } from "./core/notes.ts";
 export { copyDatabase, DATABASE, db, trim } from "./core/db.ts";
-
-// What a job can do without asking anybody: running a command, sending mail,
-// reading mail, reading and writing files in one folder, running one of an
-// agent's own scripts, reading a web page. The same work offered
-// to a model instead is "@chloejs/core/tools", and each of those is a wrapper over one
-// of these.
-export { run, type Result } from "./do/run.ts";
-export { send, type Address } from "./do/email.ts";
-export { messages, oneMessage, type Message as Mail } from "./do/mail.ts";
-export { list, read, search, write } from "./do/files.ts";
-export { script, scripts } from "./do/scripts.ts";
-export { readPage, htmlToText, isPrivate, type Page } from "./do/web.ts";

package/load/load.ts

@@ -47,7 +47,7 @@ export interface Home {
   memory: Memory & { folder: string };
 }
 
-/** A set of tools made for one agent as it loads, like readMail({ ... }). */
+/** A set of tools made for one agent as it loads, like read_mail({ ... }). */
 export type Binding = (agent: Home) => Tools;
 
 /** What defineAgent is given. */
@@ -82,7 +82,7 @@ export interface Definition {
   /** `prompt("instructions.md")`, a path inside the agent's folder, or the words themselves. */
   instructions: string | Prompt;
   /**
-   * Each tool, or a set of them like readMail({ ... }). A model calls one by
+   * Each tool, or a set of them like read_mail({ ... }). A model calls one by
    * its id. What `features` turns on is added to these and not listed here.
    */
   tools?: (Tool | Tools | Binding)[];

package/model/tools/files.ts

@@ -1,10 +1,10 @@
-// The tools over do/files.ts: one folder, offered to a model.
+// The tools over services/filesService.ts: one folder, offered to a model.
 //
 // An agent binds each one to a root it is allowed to see, and names that
 // folder in plain words for the description.
 import { z } from "zod";
 
-import { list, read, search, write } from "#chloe/do/files.ts";
+import { listFiles, readFiles, searchFiles, writeFiles } from "#chloe/services/filesService.ts";
 import { tool } from "#chloe/model/tool.ts";
 
 /**
@@ -19,29 +19,29 @@ interface Folder {
 }
 
 /** A tool that lists what is in one folder, and nothing outside it. */
-export function listIn({ root, what, id = "list_notes" }: Folder) {
+export function list_in({ root, what, id = "list_notes" }: Folder) {
   return tool({
     id,
     description: `List a folder in ${what}, so you can find the right file before reading it. Start here rather than guessing at a path.`,
     inputSchema: z.object({
       path: z.string().optional().describe("Folder to list. Omit for the top level."),
     }),
-    execute: ({ path }) => list(root, path),
+    execute: ({ path }) => listFiles(root, path),
   });
 }
 
 /** A tool that reads one file inside that folder. */
-export function readIn({ root, what, id = "read_notes" }: Folder) {
+export function read_in({ root, what, id = "read_notes" }: Folder) {
   return tool({
     id,
     description: `Read one file from ${what}. Read before answering, and read before writing: guessing from memory is how you end up confidently wrong.`,
     inputSchema: z.object({ path: z.string() }),
-    execute: ({ path }) => read(root, path),
+    execute: ({ path }) => readFiles(root, path),
   });
 }
 
 /** A tool that searches the text of the files in that folder. */
-export function searchIn({ root, what, id = "search_notes" }: Folder) {
+export function search_in({ root, what, id = "search_notes" }: Folder) {
   return tool({
     id,
     description: `Search ${what} for text, and return the matching files and lines. Search before answering anything you are not certain of.`,
@@ -49,12 +49,12 @@ export function searchIn({ root, what, id = "search_notes" }: Folder) {
       query: z.string().min(2).describe("Text to look for, case-insensitive."),
       folder: z.string().optional().describe("Narrow to one folder. Omit to search everything."),
     }),
-    execute: ({ query, folder }) => search(root, query, folder),
+    execute: ({ query, folder }) => searchFiles(root, query, folder),
   });
 }
 
 /** `commit` makes every write a git commit, for a folder that is a repo. */
-export function writeIn({ root, what, id = "write_notes", commit = false }: Folder & { commit?: boolean }) {
+export function write_in({ root, what, id = "write_notes", commit = false }: Folder & { commit?: boolean }) {
   return tool({
     id,
     description:
@@ -66,6 +66,6 @@ export function writeIn({ root, what, id = "write_notes", commit = false }: Fold
       content: z.string().min(1),
       message: z.string().optional().describe("Commit message saying what changed. Required here."),
     }),
-    execute: ({ path, content, message }) => write(root, path, content, { commit, message }),
+    execute: ({ path, content, message }) => writeFiles(root, path, content, { commit, message }),
   });
 }

package/model/tools/gmail.ts

@@ -1,10 +1,10 @@
-// The tool over do/mail.ts: reading mail, bound to a fixed search.
+// The tool over services/gmailService.ts: reading mail, bound to a fixed search.
 //
 // The binding lives in the agent's config, not in anything the model can
 // write. All the model chooses is how far back and how many.
 import { z } from "zod";
 
-import { messages, oneMessage } from "#chloe/do/mail.ts";
+import { messages, oneMessage } from "#chloe/services/gmailService.ts";
 import { tool } from "#chloe/model/tool.ts";
 
 interface Options {
@@ -25,7 +25,7 @@ interface Options {
  * A tool that reads the mail the agent is bound to. The search is the
  * binding's, and the model chooses only how far back and how many.
  */
-export function readMail({
+export function read_mail({
   search = "in:inbox",
   what = "mail in the inbox",
   days = 7,

package/model/tools/index.ts

@@ -5,12 +5,12 @@
 // its own folder, its own mailbox, its own From line, so nothing here names an
 // agent or a person.
 //
-//   import { readMail, readWeb } from "@chloejs/core/tools";
+//   import { read_mail, read_web } from "@chloejs/core/tools";
 //
 // The notes tools, write_skill and run_script are not here: an agent turns
 // them on with `features` in its definition.
 //
-// The work itself is in do/, published from "@chloejs/core", and a job calls it
+// The work itself is in services/, published as "@chloejs/core/services", and a job calls it
 // from a step rather than coming through here. If a job imports this file,
 // something is in the wrong place.
 //
@@ -18,11 +18,11 @@
 
 
 // One folder, as tools, for an agent that needs a different set.
-export { listIn, readIn, searchIn, writeIn } from "./files.ts";
+export { list_in, read_in, search_in, write_in } from "./files.ts";
 
 // Mail in, mail out.
-export { readMail } from "./gmail.ts";
-export { sendEmail } from "./send_email.ts";
+export { read_mail } from "./gmail.ts";
+export { send_email } from "./send_email.ts";
 
 // Reading a public web page.
-export { readWeb } from "./web.ts";
+export { read_web } from "./web.ts";

package/model/tools/memory.ts

@@ -4,7 +4,7 @@
 // has them: the loader adds them, so an agent's `tools` never lists them.
 import { mkdirSync } from "node:fs";
 
-import { listIn, readIn, searchIn, writeIn } from "./files.ts";
+import { list_in, read_in, search_in, write_in } from "./files.ts";
 import type { Tools } from "../tool.ts";
 
 /** The four notes tools for one agent's memory. A write is a git commit when `commit` says so. */
@@ -15,9 +15,9 @@ export function memoryTools(memory: { folder: string; commit?: boolean }): Tools
   // to fail on one missing.
   mkdirSync(folder, { recursive: true });
   return {
-    list_notes: listIn({ root: folder, what }),
-    read_notes: readIn({ root: folder, what }),
-    search_notes: searchIn({ root: folder, what }),
-    write_notes: writeIn({ root: folder, what, commit }),
+    list_notes: list_in({ root: folder, what }),
+    read_notes: read_in({ root: folder, what }),
+    search_notes: search_in({ root: folder, what }),
+    write_notes: write_in({ root: folder, what, commit }),
   };
 }

package/model/tools/run_script.ts

@@ -1,4 +1,4 @@
-// The tool over do/scripts.ts: an agent running one of its own scripts.
+// The tool over services/scriptsService.ts: an agent running one of its own scripts.
 //
 // This is the plug-and-play half of the system. A capability is a script in
 // the agent's `scripts/` folder plus a short file in its `skills/` folder
@@ -8,7 +8,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { z } from "zod";
 
 import { agentDir } from "#chloe/core/paths.ts";
-import { script, scripts } from "#chloe/do/scripts.ts";
+import { script, scripts } from "#chloe/services/scriptsService.ts";
 import { tool, type Tools } from "#chloe/model/tool.ts";
 
 /** A tool that runs one file from that agent's own `scripts/` folder. */

package/model/tools/send_email.ts

@@ -1,13 +1,13 @@
-// The tool over do/email.ts: sending one email.
+// The tool over services/emailService.ts: sending one email.
 //
 // The agent binds its own From line and its own recipients. All the model
 // writes is the subject and the body.
 import { z } from "zod";
 
-import { type Address, send } from "#chloe/do/email.ts";
+import { type EmailSender, sendEmail } from "#chloe/services/emailService.ts";
 import { tool } from "#chloe/model/tool.ts";
 
-interface Sender extends Address {
+interface Options extends EmailSender {
   /** Who it reaches and when to use it, in the agent's own words. Shown to the model. */
   when: string;
 }
@@ -16,7 +16,7 @@ interface Sender extends Address {
  * A tool that sends mail from the address the agent was given, to the address
  * it was given.
  */
-export function sendEmail({ when, ...address }: Sender) {
+export function send_email({ when, ...sender }: Options) {
   return tool({
     id: "send_email",
     description: `Send an email. ${when}`,
@@ -24,6 +24,6 @@ export function sendEmail({ when, ...address }: Sender) {
       subject: z.string().min(5).max(120),
       body: z.string().min(20).describe("Plain text. Lead with what happened and what you did."),
     }),
-    execute: ({ subject, body }) => send(address, subject, body),
+    execute: ({ subject, body }) => sendEmail(sender, subject, body),
   });
 }

package/model/tools/web.ts

@@ -1,13 +1,13 @@
-// The tool over do/web.ts: reading one public web page.
+// The tool over services/webService.ts: reading one public web page.
 import { z } from "zod";
 
-import { readPage } from "#chloe/do/web.ts";
+import { readPage } from "#chloe/services/webService.ts";
 import { tool } from "#chloe/model/tool.ts";
 
 /** A tool that reads one public web page as plain text. */
-export function readWeb() {
+export function read_web() {
   return tool({
-    id: "read_page",
+    id: "read_web",
     description:
       "Read a public web page as plain text. Links come back as `[text](url)`: to follow one, pass that url " +
       "exactly as it came back, never one you rebuilt by hand, because one changed character can make a site " +

package/model/tools/write_skill.ts

@@ -11,13 +11,13 @@
 // point at a script that a person already put there.
 //
 // Every write is a git commit, so self-improvement always leaves a diff.
-import { writeIn } from "./files.ts";
+import { write_in } from "./files.ts";
 import { agentDir } from "#chloe/core/paths.ts";
 import type { Tools } from "../tool.ts";
 
 /** A tool that rewrites one of the agent's own skills. Every write is a commit. */
 export function writeSkill(agent: string) {
-  return writeIn({
+  return write_in({
     root: `${agentDir(agent)}/skills`,
     what: "your own skills",
     id: "write_skill",

package/ops/test.ts

@@ -574,7 +574,7 @@ about("a model step that never fits");
 
 {
   about("what mail says when a person has to sign in");
-  const { explain } = await import("#chloe/do/mail.ts");
+  const { explain } = await import("#chloe/services/gmailService.ts");
 
   // The account is read from settings, which on a real box has a real one in it.
   const { settings } = await import("@chloejs/core");
@@ -833,7 +833,7 @@ about("a model step that never fits");
 
   // A tool is for a model only, whether it is one of chloe's or the agent's
   // own. A job that imports one is either doing work through a wrapper built
-  // for a model, or it wanted a `do/` folder and took the first import that
+  // for a model, or it wanted a `services/` folder and took the first import that
   // compiled. The other direction is fine: a tool may call a job's function.
   const { loadAll } = await import("@chloejs/core");
   const found = [];
@@ -1344,13 +1344,13 @@ for (const agent of (await (await import("@chloejs/core")).loadAll()).values())
   const { recall, remember } = await import("#chloe/model/memory.ts");
   remember("test/tools", "user", "What board am I on?");
   remember("test/tools", "assistant", "Board 210.", [
-    { tool: "read_page", args: { url: "https://example.com/pairings" } },
+    { tool: "read_web", args: { url: "https://example.com/pairings" } },
     { tool: "write_notes", args: { path: "chess.html", content: "x".repeat(1000) } },
   ]);
   remember("test/tools", "assistant", "Anything else?");
   const told = recall("test/tools", { limit: 10, tools: true });
   is("the next turn sees the calls, then the reply", told.map((one) => one.role), ["user", "assistant", "tool", "tool", "assistant", "assistant"]);
-  is("in the shape a turn's own calls take", told[1].tool_calls?.[0].function, { name: "read_page", arguments: '{"url":"https://example.com/pairings"}' });
+  is("in the shape a turn's own calls take", told[1].tool_calls?.[0].function, { name: "read_web", arguments: '{"url":"https://example.com/pairings"}' });
   is("a whole file written is cut short", JSON.parse(told[1].tool_calls![1].function.arguments).content.length, 303);
   is("each call is answered, or a provider refuses the history", told[2].tool_call_id, told[1].tool_calls?.[0].id);
   is("the reply itself is left as it was", told[4].content, "Board 210.");
@@ -1393,7 +1393,7 @@ for (const agent of (await (await import("@chloejs/core")).loadAll()).values())
 {
   about("reading a web page");
 
-  const { htmlToText, isPrivate, readPage } = await import("@chloejs/core");
+  const { htmlToText, isPrivate, readPage } = await import("@chloejs/core/services");
   const html =
     "<!doctype html><html><head><title>Wall &amp; chart</title><style>td{}</style></head><body>\n" +
     "<table>\n<tr><td><a href=\"report.php?section=Novice - under 900\">Novice</a></td>\n<td>239</td></tr>\n" +

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@chloejs/core",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "A job runner where asking a model is one kind of step.",
   "exports": {
     ".": "./index.ts",
-    "./channels/*": "./channels/*.ts",
+    "./channels": "./channels/index.ts",
+    "./services": "./services/index.ts",
     "./scorers": "./scorers/index.ts",
     "./timer": "./timer/index.ts",
     "./tools": "./model/tools/index.ts",
@@ -20,13 +21,13 @@
   "files": [
     "channels",
     "core",
-    "do",
     "index.ts",
     "load",
     "model",
     "ops",
     "scorers",
     "serve",
+    "services",
     "server.ts",
     "timer"
   ],

package/serve/alerts.ts

@@ -10,7 +10,7 @@
 // nobody was told about, and the sign-in is recorded either way.
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 
-import { send } from "#chloe/do/email.ts";
+import { sendEmail } from "#chloe/services/emailService.ts";
 import { STATE } from "#chloe/core/paths.ts";
 import { settings } from "#chloe/core/settings.ts";
 
@@ -45,7 +45,7 @@ function where(): { to: string[]; from: string } | null {
 function mail(subject: string, body: string): void {
   const address = where();
   if (!address) return;
-  void send({ from: address.from, to: address.to, tag: "chloe" }, subject, body).catch((error: unknown) => {
+  void sendEmail({ from: address.from, to: address.to, tag: "chloe" }, subject, body).catch((error: unknown) => {
     console.error("could not send the alert:", error instanceof Error ? error.message : error);
   });
 }

package/serve/files.ts

@@ -11,7 +11,7 @@ import { existsSync, statSync } from "node:fs";
 
 import { confine } from "#chloe/core/confine.ts";
 import { agentDir } from "#chloe/core/paths.ts";
-import { list, read, write } from "#chloe/do/files.ts";
+import { listFiles, readFiles, writeFiles } from "#chloe/services/filesService.ts";
 
 export interface Entry {
   name: string;
@@ -28,7 +28,7 @@ const JUNK = ["__pycache__", "node_modules"];
 
 /** Everything in one agent's folder, folders first, as a tree. */
 export async function tree(agent: string, path = "", depth = 0): Promise<Entry[]> {
-  const { entries } = await list(agentDir(agent), path || undefined);
+  const { entries } = await listFiles(agentDir(agent), path || undefined);
   const out: Entry[] = [];
   for (const entry of entries) {
     const dir = entry.endsWith("/");
@@ -59,12 +59,12 @@ export async function open(agent: string, path: string) {
   if (statSync(resolved).isDirectory()) {
     return { path, dir: true as const, entries: await tree(agent, path) };
   }
-  const file = await read(agentDir(agent), path);
+  const file = await readFiles(agentDir(agent), path);
   return { path, dir: false as const, content: file.content, editable: editable(path) };
 }
 
 export async function save(agent: string, path: string, content: string) {
   if (!editable(path)) throw new Error(`${path} is not markdown.`);
-  const written = await write(agentDir(agent), path, content);
+  const written = await writeFiles(agentDir(agent), path, content);
   return { path, bytes: written.bytes };
 }

package/serve/memory.ts

@@ -21,7 +21,7 @@ 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 { listFiles, readFiles, writeFiles } from "#chloe/services/filesService.ts";
 import { STATE } from "#chloe/core/paths.ts";
 import { BadRequest } from "./errors.ts";
 import { noteHead } from "./page.ts";
@@ -91,7 +91,7 @@ export async function memoryTree(agent: Agent, from = "unknown"): Promise<Entry[
 }
 
 async function walk(agent: Agent, path: string, depth = 0): Promise<Entry[]> {
-  const { entries } = await list(folder(agent), path || undefined);
+  const { entries } = await listFiles(folder(agent), path || undefined);
   const out: Entry[] = [];
   for (const entry of entries) {
     const dir = entry.endsWith("/");
@@ -139,7 +139,7 @@ export async function memoryOpen(agent: Agent, path: string, from: string) {
     await record(agent, "list", path, from);
     return { path, dir: true as const, entries: await walk(agent, path) };
   }
-  const file = await read(folder(agent), path);
+  const file = await readFiles(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 };
@@ -213,7 +213,7 @@ export function withHead(html: string, head: string): string {
 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, {
+  const written = await writeFiles(folder(agent), path, content, {
     commit,
     message: commit ? `memory: ${path} from the site` : undefined,
   });

package/services/emailService.ts

@@ -0,0 +1,73 @@
+// Sending one email.
+//
+// The caller supplies who it is from and who it is to. Which provider carries
+// it is email.provider in settings, and each provider reads its own section
+// of settings.local.json for its key (resend.api_key for Resend).
+//
+// The tool a model reaches is model/tools/send_email.ts, which calls
+// this. A job calls this directly, from a step.
+
+import { setting, settings } from "#chloe/core/settings.ts";
+
+/**
+ * Who an agent's mail comes from, who it goes to, and the tag in front of
+ * every subject.
+ */
+export interface EmailSender {
+  /** The From line, e.g. "Backups <info@example.com>". */
+  from: string;
+  /** Who it goes to. */
+  to: string[];
+  /** Prefix put in front of every subject, so an inbox can be filtered. */
+  tag?: string;
+}
+
+/** One message, ready to go: the tag is already in the subject. */
+export interface Email {
+  from: string;
+  to: string[];
+  subject: string;
+  body: string;
+}
+
+/** Something that can carry an email. Returns the provider's id for it, if it gives one. */
+export interface EmailProvider {
+  send(email: Email): Promise<{ id?: string }>;
+}
+
+const resend: EmailProvider = {
+  async send({ from, to, subject, body }) {
+    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 }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok) {
+      throw new Error(`Resend refused the message (${response.status}): ${await response.text()}`);
+    }
+    return (await response.json()) as { id?: string };
+  },
+};
+
+/** 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 };
+
+/** 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,
+  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({
+    from,
+    to,
+    subject: tag ? `[${tag}] ${subject}` : subject,
+    body,
+  });
+  return { sent: true, id, subject };
+}

package/{do/files.ts → services/filesService.ts}

@@ -15,10 +15,10 @@ import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
 import { confine } from "#chloe/core/confine.ts";
-import { run } from "./run.ts";
+import { run } from "./runService.ts";
 
 /** List a folder. `path` is relative to `root`, and omitting it means the top. */
-export async function list(root: string, path?: string) {
+export async function listFiles(root: string, path?: string) {
   const resolved = path ? confine(root, path) : root;
   const entries = await readdir(resolved, { withFileTypes: true });
   return {
@@ -31,14 +31,14 @@ export async function list(root: string, path?: string) {
 }
 
 /** Read one file. `path` is relative to `root` and cannot leave it. */
-export async function read(root: string, path: string) {
+export async function readFiles(root: string, path: string) {
   const resolved = confine(root, path);
   const content = await readFile(resolved, "utf8");
   return { path: resolved, bytes: content.length, content };
 }
 
 /** Search a folder for text, case-insensitive. `folder` narrows it. */
-export async function search(root: string, query: string, folder?: string) {
+export async function searchFiles(root: string, query: string, folder?: string) {
   const target = folder ? confine(root, folder) : root;
   // ripgrep if the box has it, grep otherwise. An earlier version assumed
   // ripgrep, and when it was not installed every search quietly answered
@@ -68,7 +68,7 @@ export async function search(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.
  */
-export async function write(
+export async function writeFiles(
   root: string,
   path: string,
   content: string,

package/{do/mail.ts → services/gmailService.ts}

@@ -11,7 +11,7 @@
 // The tool a model reaches is model/tools/gmail.ts, which calls this
 // with the same binding, so a job does not get a wider search for skipping
 // the model.
-import { run } from "./run.ts";
+import { run } from "./runService.ts";
 import { setting, settings } from "#chloe/core/settings.ts";
 
 const GOG = "gog";

package/services/index.ts

@@ -0,0 +1,16 @@
+// What a job can do without asking anybody: running a command, sending mail,
+// reading mail, reading and writing files in one folder, running one of an
+// agent's own scripts, reading a web page.
+//
+//   import { run, sendEmail } from "@chloejs/core/services";
+//
+// The same work offered to a model instead is "@chloejs/core/tools", and each
+// of those is a wrapper over one of these. Same rule as `index.ts`: adding a
+// name here is publishing it.
+
+export { run, type Result } from "./runService.ts";
+export { sendEmail, type EmailSender } from "./emailService.ts";
+export { messages, oneMessage, type Message as Mail } from "./gmailService.ts";
+export { listFiles, readFiles, searchFiles, writeFiles } from "./filesService.ts";
+export { script, scripts } from "./scriptsService.ts";
+export { readPage, htmlToText, isPrivate, type Page } from "./webService.ts";

package/{do/scripts.ts → services/scriptsService.ts}

@@ -11,7 +11,7 @@ import { readdir } from "node:fs/promises";
 
 import { agentDir } from "#chloe/core/paths.ts";
 import { settings } from "#chloe/core/settings.ts";
-import { run, type Result } from "./run.ts";
+import { run, type Result } from "./runService.ts";
 
 /** What this agent has in scripts/, sorted. Nothing hidden. */
 export async function scripts(agent: string): Promise<string[]> {

package/do/email.ts

@@ -1,45 +0,0 @@
-// Sending one email.
-//
-// The caller supplies who it is from and who it is to; this file only knows
-// how to send. The key is resend.api_key in settings.local.json.
-//
-// The tool a model reaches is model/tools/send_email.ts, which calls
-// this. A job calls this directly, from a step.
-
-import { setting, settings } from "#chloe/core/settings.ts";
-
-/**
- * Who an agent's mail comes from, who it goes to, and the tag in front of
- * every subject.
- */
-export interface Address {
-  /** The From line, e.g. "Backups <info@example.com>". */
-  from: string;
-  /** Who it goes to. */
-  to: string[];
-  /** Prefix put in front of every subject, so an inbox can be filtered. */
-  tag?: string;
-}
-
-/** Sends one email and returns its id. The tag is put in front of the subject. */
-export async function send(
-  { from, to, tag }: Address,
-  subject: string,
-  body: string,
-): Promise<{ sent: true; id?: string; subject: string }> {
-  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.");
-  // Refuse rather than send nowhere.
-  if (to.length === 0) throw new Error("Nobody to send to. The address belongs in settings.local.json.");
-  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: tag ? `[${tag}] ${subject}` : subject, text: body }),
-    signal: AbortSignal.timeout(30_000),
-  });
-  if (!response.ok) {
-    throw new Error(`Resend refused the message (${response.status}): ${await response.text()}`);
-  }
-  const sent = (await response.json()) as { id?: string };
-  return { sent: true, id: sent.id, subject };
-}