@chloejs/core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Martinez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# Chloe
+
+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
+decide where deterministic work ends and where non-deterministic work begins.
+
+```sh
+npm install @chloejs/core @chloejs/ui
+```
+
+- **No build step**, and an edit to a job is live in under a second
+- **One dependency**, zod, and one SQLite file
+- **Node 22.18** or newer
+
+[Get started](https://chloejs.org/docs/start) ·
+[Examples](https://chloejs.org/examples) ·
+[Primitives](https://chloejs.org/docs/primitives)
+
+## The least autonomy that does the job
+
+Three ways to do a piece of work. Start at the top, and move down only when you
+have to.
+
+| | | |
+| --- | --- | --- |
+| `work.step()` | I know what to do. | Deterministic work. You control the workflow and the action. |
+| `work.model()` | I know what to ask. | Judgement, in a shape. You control the workflow, the model controls the answer. |
+| `work.agent()` | I know what I want. | Bounded autonomy. You control the goal and the boundaries, the model controls the order. |
+
+There is a fourth. `work.ask()` stops the job and waits for a person.
+
+## Ordinary code, one model decision, optional autonomy
+
+A whole job, from the example on chloejs.org. Code loads the inbox, a model says
+what each message is about, and the ones that need looking into get an agent.
+
+```ts
+export default defineJob({
+  id: "order-issues",
+  cron: every(15).minutes,
+  description: "Reads what customers wrote in and looks into the ones that need looking into.",
+  run: async (work) => {
+    const messages = await work.step("load messages", () => unread());
+
+    const looked: string[] = [];
+    for (const message of messages) {
+      const issue = await work.model("classify issue", {
+        prompt: message.text,
+        output: Issue,
+      });
+      if (!issue.needsInvestigation) continue;
+
+      const found = await work.agent("investigate issue", {
+        goal: `Find out what went wrong for customer ${message.customer}, and recommend what to do.`,
+        tools: [getOrders, pastMessages],
+        maxSteps: 6,
+        budget: 0.05,
+      });
+
+      looked.push(`${message.id}: ${found}`);
+    }
+
+    return { looked };
+  },
+});
+```
+
+## Keep the application in charge
+
+Your rules, loops, conditions and queries stay in TypeScript. The model is asked
+one thing, and the `if` above it decides whether to ask at all.
+
+```ts
+const late = orders.filter((order) => order.daysLate > 2);
+if (late.length === 0) return;
+
+const summary = await work.model("summarise the delays", {
+  prompt: late.map(describe).join("\n"),
+  output: Summary,
+});
+```
+
+A morning with nothing late costs nothing.
+
+## You can point at the line that asks a model
+
+The run record has one line per step, with what it was, how long it took and
+what it cost. A job that quietly grew a second model call shows up as a second
+line and a bigger number.
+
+## Sometimes you know the goal, not the steps
+
+The model chooses the order. You choose what it can reach and how far it can
+go: `tools` is all it can reach, `approve` is which of those calls may run,
+`maxSteps` and `budget` are how far it can go and what it may spend, and
+`output` is the shape of the answer. Everything it did is on the run.
+
+## Some decisions should not belong to a model
+
+The run stops, the question goes to whoever should answer it, and the job
+carries on when they do. It can wait days, and it survives a restart while it
+waits.
+
+```ts
+const approved = await work.ask("refund $2,400?", {
+  question: "A-4417 arrived broken. Refund it?",
+  answer: z.boolean(),
+  within: "2d",
+  otherwise: false,
+});
+
+if (approved) await work.step("issue refund", () => refund(order));
+```
+
+The answer is checked against the shape the ask named. No model is involved.
+
+## Jobs survive the real world
+
+Steps, model calls, agent loops and human pauses are all part of one durable
+run, and you can open any of them.
+
+- A finished step replays from the record.
+- A job resumes after a restart.
+- An approval can wait for days.
+- Every tool call an agent made is recorded.
+- Cost is tracked per step and per run.
+- Two runs of the same job never overlap.
+
+One rule makes the replay safe: **work happens inside a step, and code outside a
+step only decides.** A step is written down, so it never runs twice. A line
+outside one runs again on every resume, so it must not send, write or spend.
+
+## What comes with it
+
+| | |
+| --- | --- |
+| Durable jobs | Steps are written down as they finish, and replayed on a resume. |
+| Schedules | Cron lines in TypeScript, with real time zones. |
+| Models | Any model the gateway reaches, and a job can pick its own. |
+| Agents | Tools, approvals and a budget, set where the step is written. |
+| Tools | A description, a schema and one call. Typed at both ends. |
+| Human approvals | A run parks for days and carries on when somebody answers. |
+| Channels | Telegram and Slack, one file each. A question goes out where the person is. |
+| Memory | Notes an agent keeps, and skills it can rewrite. |
+| Run history | Every step of every run, with its arguments and its answer. |
+| Cost tracking | Per step, per run, per job. |
+| Structured output | Zod on every model and agent answer, retried once. |
+| Testing and evals | Jobs run for real against a stand-in gateway. Prompts are scored. |
+
+## Code is tested. Words are scored.
+
+Your deterministic logic gets ordinary tests. Your prompts get evals. Neither
+spends real money: a test runs against a stand-in gateway, and an eval answers
+every tool from the case.
+
+```sh
+npm run test          # the jobs: does it do the thing
+npm run evals <name>  # the prompts: did the model decide well
+```
+
+## Run it wherever Node runs
+
+Your code, your models, your machine. One process serves the page, keeps every
+cron line and answers the channels. The runtime's only dependency is zod and its
+state is one SQLite file, so moving machine is copying a folder.
+
+Three files, and you have an agent:
+
+```
+chloe.config.ts        the agents this copy runs
+settings.json          which model, and how to reach it
+your-agent/agent.ts    what the agent is: its jobs, tools and channels
+```
+
+```sh
+npm run account                  # make the one account
+npm start                        # the one process, on 127.0.0.1:3067
+npm run agent <name>             # talk to one agent
+npm run agent <name> <job>       # run one job now, without waiting for its cron line
+```
+
+Without `@chloejs/ui` the runtime serves a plain page of its own. With it, that
+page is the dashboard. The runtime never names that package: it serves whatever
+installed package declares a page.
+
+## What is in here
+
+The package is this repo: what is at the top is what is published.
+
+```
+index.ts     what "@chloejs/core" is when you import it
+server.ts    the server, and the only thing that is run
+model/       asking a model, and tools/, the only thing a model can be handed
+load/        what an agent and a job are, and reading them off disk
+timer/       cron lines and every(), published as "@chloejs/core/timer"
+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
+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`.
+
+## Use code when you know what to do. Use AI when you do not.
+
+Start with a job that asks nobody anything. Add the step that needs judgement
+when you find it, and read what it cost.
+
+The docs are at [chloejs.org](https://chloejs.org). Its reference pages are read
+out of this source on every push to `main`, so they cannot describe a version of
+the code that does not exist.
+
+MIT.

package/channels/api.ts

@@ -0,0 +1,41 @@
+// Opting one agent in to being reached by another system.
+//
+//   // agents/<name>/agent.ts
+//   import { apiChannel } from "@chloejs/core/channels/api";
+//   channels: [apiChannel()],
+//
+// Binding it makes two routes answer for that agent when the caller holds a
+// token, made at /tokens on the runtime site:
+//
+//   POST /api/agents/<name>/chat          one turn, and a reply
+//   POST /api/agents/<name>/job/<job>     run one of its jobs now
+//
+//   curl -X POST http://127.0.0.1:3067/api/agents/shop/chat \
+//     -H "authorization: Bearer $CHLOE_TOKEN" \
+//     -H "content-type: application/json" \
+//     -d '{"prompt":"how many orders are late?"}'
+//
+//   {"runId":"...","text":"Three.","steps":2,"cost":0.0031}
+//
+// `thread` is optional and is the caller's own name for a conversation: send
+// the same one again and the agent remembers what was said. A token's threads
+// are kept apart from the ones a person started.
+//
+// An agent without this channel is not on the API. Somebody signed in on the
+// box can still talk to it from the site, because that is the account and the
+// account can do everything. A token cannot, and gets a 403 saying so.
+//
+// Why this is a channel and not a flag: a channel is the thing an agent's
+// definition already lists to say how it can be reached, and being reachable
+// by another system belongs in that list beside telegram. It listens to
+// nothing and starts nothing, because the server already answers those two
+// routes. What this adds is the permission.
+//
+// It does not carry a job's question out to anybody, because HTTP cannot push.
+// A job that stops to ask waits in GET /api/parked like it always did.
+import type { Channel, ChatHistory } from "#chloe/load/load.ts";
+
+/** `chatHistory` is how much of a caller's thread a turn is shown. */
+export function apiChannel(options: { chatHistory?: ChatHistory } = {}): Channel {
+  return { name: "api", chatHistory: options.chatHistory, start: () => ({ stop: () => {} }) };
+}

package/channels/shared.ts

@@ -0,0 +1,250 @@
+// What every channel shares: what happens to a message, whichever channel it
+// came in on. A channel turns its platform's message into an `Incoming`, calls
+// receive(), and sends back the text it returns. Everything else is decided
+// 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";
+//
+// In order, and the first that applies decides:
+//
+//   1. Somebody not in allowFrom gets nothing. While allowFrom is empty, a
+//      private message is told the sender's id, which is what goes in it.
+//   2. An answer to a job waiting on this chat goes to that job.
+//   3. In a group, a message that is not for the agent is left alone, unless
+//      the channel's inGroups is "always".
+//   4. "/<job id> ..." runs that job. "_" stands for "-", because some
+//      platforms allow no hyphens in a command.
+//   5. A message one of the agent's jobs `answers` runs that job.
+//   6. Anything else is a turn, shown the chat's recent conversation.
+//
+// Rules 4 and 5 are code, never a model: which job gets a message is a rule
+// somebody can write down. What a job said in a chat is kept in that chat's
+// conversation, so the next turn knows it happened.
+import type { Agent, ChatHistory, Job } from "#chloe/load/load.ts";
+import type { Attachment } from "#chloe/model/model.ts";
+import { remember } from "#chloe/model/memory.ts";
+import { clock, type Fired } from "#chloe/core/clock.ts";
+import { answer, waitingOn, WrongInput } from "#chloe/core/steps.ts";
+import { turn } from "#chloe/core/turn.ts";
+
+/** One message, in the words every channel shares. */
+export interface Incoming {
+  /** The channel's name, like "telegram". What the log shows, and the first half of an address. */
+  channel: string;
+  /** Where it was said, as the channel names it. `${channel}:${chat}` is how a job asks back here. */
+  chat: string;
+  /** The conversation it belongs to: one per chat, or per topic in a forum. Empty for none, so nothing is remembered. */
+  thread: string;
+  from: { id: string; name: string };
+  text: string;
+  /** A one-to-one chat, rather than a group. */
+  private: boolean;
+  /** In a group: it mentions the agent or replies to it. */
+  addressed?: boolean;
+  chatTitle?: string;
+  /** The message this one replies to, when it is one. */
+  replyTo?: string;
+  /**
+   * Facts about where it was said, handed to the model ahead of the message
+   * with who sent it: "chat_type", "chat_title". Without them the model is
+   * handed the message alone, which is right for a caller that is a program.
+   */
+  context?: Record<string, string>;
+  /** The files on it, fetched only when a turn is going to read them. */
+  files?: () => Promise<{ attachments?: Attachment[]; text?: string; notes?: string[] }>;
+  /** A model for this one turn, when the channel lets its caller pick. */
+  model?: string;
+}
+
+/** Who a channel answers. Each channel takes these as options and hands them over. */
+export interface Rules {
+  /** Ids that may reach the agent. Unset, anybody who got this far may, which is right only behind a login. */
+  allowFrom?: (string | number)[];
+  /** In a group, "when-addressed" (the default) answers a command, a mention or a reply. "always" answers everything. */
+  inGroups?: "when-addressed" | "always";
+  /** How much of a conversation on this channel a turn is shown. */
+  chatHistory?: ChatHistory;
+  /**
+   * Send what the model writes on its way to an answer (a "let me check" line,
+   * or a draft it goes on to improve) as it writes it, rather than only the
+   * answer it ends on. Off unless true. Needs a channel that can send more
+   * than one reply, so it does nothing on the API.
+   */
+  sendWhileWorking?: boolean;
+}
+
+/** What a channel can do while a message is being dealt with. */
+export interface While {
+  /** Called once there is work to do, for "typing..."; what it returns is called when the work is over. */
+  working?: () => () => void;
+  /** Sends one message to the chat. What sendWhileWorking uses. */
+  send?: (text: string) => Promise<void>;
+}
+
+/** What came of a message. Nothing at all means it was not for the agent. */
+export interface Handled {
+  /** What to send back. Empty when there is nothing to send, because a question already went out. */
+  text: string;
+  runId?: string;
+  steps: number;
+  cost: number;
+  /** The job that took it, when one did. */
+  job?: string;
+}
+
+/**
+ * Decides what a message is, does it, and says what to send back. See While
+ * for what a channel can hand over to be used on the way.
+ */
+export async function receive(agent: Agent, message: Incoming, rules: Rules = {}, whileWorking: While = {}): Promise<Handled | undefined> {
+  const working = whileWorking.working ?? (() => () => {});
+  const { channel, from, text } = message;
+  const said = (words: string): Handled => ({ text: words, steps: 0, cost: 0 });
+
+  if (rules.allowFrom) {
+    if (rules.allowFrom.length === 0) {
+      console.log(`${channel}: ${from.id} wrote to ${agent.name}. Add ${from.id} to allowFrom in ${agent.name}'s ${channel} channel.`);
+      const Channel = channel.charAt(0).toUpperCase() + channel.slice(1);
+      return message.private ? said(`Your ${Channel} user id is ${from.id}. Add it to allowFrom in ${agent.name}'s ${channel} channel.`) : undefined;
+    }
+    if (!rules.allowFrom.map(String).includes(from.id)) {
+      // In a group the agent sees everybody's messages, and most are not for it.
+      if (message.private) console.warn(`${channel}: ${agent.name} is ignoring ${from.id} (${from.name}), not in allowFrom`);
+      return undefined;
+    }
+  }
+
+  const waiting = text ? waitingOn(`${channel}:${message.chat}`, agent.name) : undefined;
+  if (waiting) return during(working, () => answered(agent, message, waiting.id, waiting.job));
+
+  const forAgent = message.private || message.addressed || rules.inGroups === "always" || text.startsWith("/");
+  if (!forAgent) return undefined;
+
+  const job = text ? jobFor(agent, text) : undefined;
+  if (job && clock()) return during(working, () => started(agent, message, job.job, job.text));
+
+  return during(working, () => chatted(agent, message, rules, whileWorking.send));
+}
+
+/** The commands a channel can offer in its own menu: each job, with "_" for "-". */
+export function commands(agent: Agent): { command: string; description: string }[] {
+  return agent.jobs
+    .map((job) => ({ command: job.id.replace(/-/g, "_").toLowerCase(), description: (job.description || job.id).slice(0, 256) }))
+    .filter((one) => /^[a-z0-9_]{1,32}$/.test(one.command));
+}
+
+async function during(working: () => () => void, work: () => Promise<Handled>): Promise<Handled> {
+  const stop = working();
+  try {
+    return await work();
+  } finally {
+    stop();
+  }
+}
+
+/** The job a message is for, by command or by a job that answers it, and the text it is started with. */
+function jobFor(agent: Agent, text: string): { job: Job; text: string } | undefined {
+  if (text.startsWith("/")) {
+    const [word, ...rest] = text.trim().split(/\s+/);
+    const asked = word.slice(1).split("@")[0].toLowerCase();
+    const job = agent.jobs.find((one) => one.id === asked || one.id === asked.replace(/_/g, "-"));
+    // Not one of this agent's jobs, so it is a message that starts with a
+    // slash, and goes on to be asked of the model like any other.
+    if (job) return { job, text: text.slice(word.length).trim() || rest.join(" ") };
+  }
+  const job = agent.jobs.find((one) => {
+    try {
+      return one.answers?.(text) === true;
+    } catch (error) {
+      console.error(`${agent.name}/${one.id}: its answers check failed:`, (error as Error).message);
+      return false;
+    }
+  });
+  return job && { job, text };
+}
+
+/** What a job said, as a reply: its own reply, its summary line, or what it returned. */
+function replyOf(result: Fired, job: Job): string {
+  if ("parked" in result && result.parked) return "";
+  return result.reply || result.summary || result.text || `${job.id}: done.`;
+}
+
+/** A job's exchange, kept in the chat's conversation the way a turn keeps its own. */
+function kept(message: Incoming, reply: string): void {
+  if (!message.thread) return;
+  remember(message.thread, "user", message.text);
+  remember(message.thread, "assistant", reply);
+}
+
+async function started(agent: Agent, message: Incoming, job: Job, text: string): Promise<Handled> {
+  const input = {
+    text,
+    from: message.channel,
+    chat: message.chat,
+    chatTitle: message.chatTitle ?? "",
+    user: message.from.name,
+    thread: message.thread,
+    replyTo: message.replyTo ?? "",
+  };
+  try {
+    const result = await clock()!.fire(agent, job, input, message.channel);
+    if (!result) return { text: `${job.id} is already running. I will not start a second one.`, steps: 0, cost: 0, job: job.id };
+    const reply = replyOf(result, job);
+    kept(message, reply);
+    return { text: reply, runId: result.runId, steps: result.steps, cost: result.cost, job: job.id };
+  } catch (error) {
+    // What was sent did not fit the job, which is worth saying where it was
+    // sent: it is the message that has to change.
+    const why = error instanceof WrongInput ? error.message : "It is in the logs on the box.";
+    if (!(error instanceof WrongInput)) console.error(`${agent.name}/${job.id}: failed`, error);
+    return { text: `I could not run ${job.id}. ${why}`, steps: 0, cost: 0, job: job.id };
+  }
+}
+
+async function answered(agent: Agent, message: Incoming, runId: string, job: string): Promise<Handled> {
+  try {
+    const result = await answer(runId, message.text, new Map([[agent.name, agent]]));
+    // Still parked means the answer did not fit, and the job has already asked again.
+    const reply = result.parked ? "" : result.reply || result.summary || result.text || "Done.";
+    kept(message, reply);
+    return { text: reply, runId: result.runId, steps: result.steps, cost: result.cost, job };
+  } catch (error) {
+    console.error(`${message.channel}: answering a waiting job failed`, error);
+    return { text: "I could not carry that job on. It is in the logs on the box.", steps: 0, cost: 0 };
+  }
+}
+
+async function chatted(agent: Agent, message: Incoming, rules: Rules, send?: (text: string) => Promise<void>): Promise<Handled> {
+  // One after another, and all of them out before the answer is.
+  let sending = Promise.resolve();
+  const said =
+    rules.sendWhileWorking && send
+      ? (text: string) => {
+          sending = sending.then(() => send(text)).catch((error) => console.error(`${message.channel}: sending on the way failed`, error));
+          // Sent, so kept: the next turn should know it was said.
+          if (message.thread) remember(message.thread, "assistant", text);
+        }
+      : undefined;
+  try {
+    const files = (await message.files?.()) ?? {};
+    const facts = message.context && { from: message.from.name, ...message.context };
+    const context = facts && [`<${message.channel}_context>`, ...Object.entries(facts).map(([k, v]) => `${k}: ${v}`), `</${message.channel}_context>`].join("\n");
+    const result = await turn({
+      agent,
+      prompt: [context, message.text, files.text, ...(files.notes ?? [])].filter(Boolean).join("\n\n"),
+      attachments: files.attachments?.length ? files.attachments : undefined,
+      thread: message.thread || undefined,
+      history: rules.chatHistory,
+      said,
+      model: message.model,
+      source: message.channel,
+      owner: `${message.channel}:${message.from.id}`,
+    });
+    await sending;
+    return { text: result.text || "(no reply)", runId: result.runId, steps: result.steps, cost: result.cost };
+  } catch (error) {
+    console.error(`${message.channel}: turn failed`, error);
+    return { text: "Something went wrong on my end. It is in the logs on the box.", steps: 0, cost: 0 };
+  }
+}