@chloejs/core 0.2.0 → 0.2.2

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,7 +202,7 @@ 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
 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

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

@@ -44,9 +44,9 @@ export { copyDatabase, DATABASE, db, trim } from "./core/db.ts";
 // 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";
+export { run, type Result } from "./services/runService.ts";
+export { sendEmail, type EmailSender } from "./services/emailService.ts";
+export { messages, oneMessage, type Message as Mail } from "./services/gmailService.ts";
+export { list, read, search, write } from "./services/filesService.ts";
+export { script, scripts } from "./services/scriptsService.ts";
+export { readPage, htmlToText, isPrivate, type Page } from "./services/webService.ts";

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 { list, read, search, write } from "#chloe/services/filesService.ts";
 import { tool } from "#chloe/model/tool.ts";
 
 /**

package/model/tools/gmail.ts

@@ -1,17 +1,21 @@
-// 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 {
-  /** Gmail query this agent may see, and nothing else. Set in its config. */
-  search: string;
+  /**
+   * Gmail query this agent may see, and nothing else. Set in its config.
+   * Unsaid it is `in:inbox`, which is the whole inbox: a binding of its own
+   * is what keeps the agent to one slice of the mailbox.
+   */
+  search?: string;
   /** How to describe that mail in the tool's description, in plain words. */
-  what: string;
+  what?: string;
   /** Days back when the agent does not say. */
   days?: number;
   id?: string;
@@ -21,7 +25,12 @@ 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({ search, what, days = 7, id = "read_mail" }: Options) {
+export function readMail({
+  search = "in:inbox",
+  what = "mail in the inbox",
+  days = 7,
+  id = "read_mail",
+}: Options = {}) {
   return tool({
     id,
     description:

package/model/tools/index.ts

@@ -10,7 +10,7 @@
 // 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 from "@chloejs/core", 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.
 //

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 as send } 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 sendEmail({ 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 }) => send(sender, subject, body),
   });
 }

package/model/tools/web.ts

@@ -1,7 +1,7 @@
-// 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. */

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 = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chloejs/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "A job runner where asking a model is one kind of step.",
   "exports": {
@@ -20,13 +20,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 { list, read, write } from "#chloe/services/filesService.ts";
 
 export interface Entry {
   name: string;

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 { list, read, write } from "#chloe/services/filesService.ts";
 import { STATE } from "#chloe/core/paths.ts";
 import { BadRequest } from "./errors.ts";
 import { noteHead } from "./page.ts";

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,7 +15,7 @@ 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) {

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/{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 };
-}