@chloejs/core 0.2.0

package/model/claude.ts

@@ -0,0 +1,261 @@
+// Asking the model through the Claude Code CLI rather than over HTTP.
+//
+// This exists for the credential, not the model. A Claude subscription
+// authorises the CLI; it is not an API key and there is nothing in it to put in
+// a bearer header. So a box with a subscription and no gateway credit runs the
+// agents through here instead. Set MODEL_VIA=claude.
+//
+// The CLI brings its own tools and its own loop. Both are switched off, because
+// chloe runs the tools itself, checks each one against its schema and writes
+// every call down. A model that quietly read a file would leave nothing in the
+// run record, which is the one thing this repo will not give up. So the tools
+// are described in the prompt and asked for as JSON.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+
+import { setting, settings } from "#chloe/core/settings.ts";
+
+import type { Answer, Ask, Message, ToolCall, ToolSpec } from "./model.ts";
+
+/**
+ * The CLI names a model without a provider in front of it, and writes a version
+ * with a dash where the gateway writes a dot: "anthropic/claude-haiku-4.5"
+ * there is "claude-haiku-4-5" here. A non-Anthropic model says so rather than
+ * being handed over and refused.
+ */
+export function cliModel(model: string): string {
+  const at = model.indexOf("/");
+  const provider = at < 0 ? "anthropic" : model.slice(0, at);
+  if (provider !== "anthropic") {
+    throw new Error(
+      `MODEL_VIA=claude can only run Anthropic models, and this one asks for ${JSON.stringify(model)}. ` +
+        `Either change the model or set MODEL_VIA=gateway.`,
+    );
+  }
+  return model.slice(at + 1).replace(/\./g, "-");
+}
+
+/** What the model is told about tools it cannot call itself. */
+function protocol(tools: ToolSpec[]): string {
+  const list = tools
+    .map((t) => `### ${t.name}\n${t.description}\n\nArguments, as JSON Schema:\n${JSON.stringify(t.parameters)}`)
+    .join("\n\n");
+
+  return [
+    "# Tools",
+    "",
+    "You cannot run a tool yourself. To use one, end your reply with this and nothing after it:",
+    "",
+    '{"tool": "<name>", "arguments": { ... }}',
+    "",
+    "It must start its own line and be the last thing you write. A sentence before it is",
+    "fine. The result comes back and you are asked again, so ask for one tool at a time.",
+    "To answer instead, reply in plain words and end with no such object.",
+    "",
+    list,
+  ].join("\n");
+}
+
+function render(message: Message): string {
+  if (message.role === "tool") {
+    return `[result]\n${message.content}`;
+  }
+  if (message.role === "assistant") {
+    const asked = (message.tool_calls ?? [])
+      .map((c) => `[asked for ${c.function.name} with ${c.function.arguments}]`)
+      .join("\n");
+    return [`[you]`, message.content, asked].filter(Boolean).join("\n");
+  }
+  return `[${message.role}]\n${message.content}`;
+}
+
+/**
+ * Split a reply into what it said and what it asked for.
+ *
+ * The object has to be last and has to start its own line. Models narrate
+ * before asking ("Let me check the site first."), and telling them not to does
+ * not stop it, so the narration is kept and passed on rather than thrown away.
+ * Requiring its own line at the end is what keeps a reply that merely writes
+ * about JSON from being read as a request.
+ */
+export function readReply(text: string, tools: ToolSpec[] = []): { said: string; call?: ToolCall } {
+  const whole = text.trim();
+  const tagged = readTagged(whole, tools);
+  if (tagged) return tagged;
+  const fenced = whole.match(/^([\s\S]*?)```(?:json)?\s*\n([\s\S]*?)\n?```\s*$/);
+  const before = fenced ? fenced[1] : whole;
+  const tail = fenced ? fenced[2].trim() : "";
+
+  const candidates = tail ? [{ body: tail, said: before }] : [];
+  if (!tail) {
+    // Every line that opens an object, latest first: the last one that parses
+    // to the end of the reply is the request.
+    const lines = whole.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+      if (lines[i].startsWith("{")) {
+        candidates.push({ body: lines.slice(i).join("\n").trim(), said: lines.slice(0, i).join("\n") });
+      }
+    }
+  }
+
+  for (const { body, said } of candidates) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      continue;
+    }
+    const asked = parsed as { tool?: unknown; arguments?: unknown };
+    if (typeof asked.tool !== "string" || !asked.tool) continue;
+    return {
+      said: said.trim(),
+      call: {
+        id: randomUUID(),
+        type: "function",
+        function: { name: asked.tool, arguments: JSON.stringify(asked.arguments ?? {}) },
+      },
+    };
+  }
+  return { said: whole };
+}
+
+/**
+ * The same request in the tag form Claude is trained on, which it sometimes
+ * writes despite being told the JSON one:
+ * `<invoke name="x"><parameter name="path">a.html</parameter></invoke>`.
+ * The first one is the request, the way one JSON object is, and anything after
+ * it is dropped: it is often the same call written again. Every value is text in
+ * this form, so one the tool's schema says is not a string is read as JSON,
+ * which is how a number or a list arrives as one.
+ */
+function readTagged(whole: string, tools: ToolSpec[]): { said: string; call: ToolCall } | undefined {
+  const start = whole.search(/<(?:[\w-]+:)?invoke\s+name="/);
+  if (start < 0) return undefined;
+  const opened = whole.slice(start).match(/^<(?:[\w-]+:)?invoke\s+name="([^"]+)"\s*>([\s\S]*?)(?:<\/(?:[\w-]+:)?invoke>|$)/);
+  if (!opened) return undefined;
+  const wants = (tools.find((t) => t.name === opened[1])?.parameters as { properties?: Record<string, { type?: unknown }> })
+    ?.properties;
+  const args: Record<string, unknown> = {};
+  for (const [, key, raw] of opened[2].matchAll(/<(?:[\w-]+:)?parameter\s+name="([^"]+)"\s*>([\s\S]*?)<\/(?:[\w-]+:)?parameter>/g)) {
+    if (wants?.[key]?.type === "string") {
+      args[key] = raw;
+      continue;
+    }
+    try {
+      args[key] = JSON.parse(raw);
+    } catch {
+      args[key] = raw;
+    }
+  }
+  return {
+    said: whole.slice(0, start).replace(/<(?:[\w-]+:)?function_calls>\s*$/, "").trim(),
+    call: { id: randomUUID(), type: "function", function: { name: opened[1], arguments: JSON.stringify(args) } },
+  };
+}
+
+interface CliAnswer {
+  result?: string;
+  is_error?: boolean;
+  subtype?: string;
+  total_cost_usd?: number;
+  usage?: { input_tokens?: number; output_tokens?: number };
+}
+
+/**
+ * The prompt goes in on stdin, never as an argument: Linux caps one argument at
+ * 128KB and a long conversation goes past that.
+ */
+function invoke(args: string[], input: string, signal?: AbortSignal): Promise<{ code: number; out: string; err: string }> {
+  return new Promise((done, fail) => {
+    const cli = setting("claude", "CLAUDE_BIN");
+    const child = spawn(cli, args, { stdio: ["pipe", "pipe", "pipe"], signal });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d: Buffer) => (out += d.toString()));
+    child.stderr.on("data", (d: Buffer) => (err += d.toString()));
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      fail(
+        error.code === "ENOENT"
+          ? new Error(`model.via is "claude", but ${JSON.stringify(cli)} is not on the path. Install Claude Code, or put it on the path.`)
+          : error,
+      );
+    });
+    child.on("close", (code) => done({ code: code ?? 0, out, err }));
+    child.stdin.end(input);
+  });
+}
+
+export async function viaClaude({ model, messages, tools, signal }: Ask): Promise<Answer> {
+  const system = [
+    ...messages.filter((m) => m.role === "system").map((m) => m.content),
+    ...(tools?.length ? [protocol(tools)] : []),
+  ].join("\n\n");
+
+  const transcript = messages.filter((m) => m.role !== "system").map(render).join("\n\n");
+
+  const args = [
+    "-p",
+    "--output-format",
+    "json",
+    "--model",
+    cliModel(model),
+    // No tools of its own, no settings from this machine, no MCP servers: the
+    // same prompt has to mean the same thing on anyone's box.
+    "--restricted",
+    "--tools",
+    "",
+    "--strict-mcp-config",
+    "--exclude-dynamic-system-prompt-sections",
+    "--system-prompt",
+    system,
+  ];
+
+  // Files cannot go in plain text, so a turn with any is sent as one message
+  // of blocks instead, which the CLI only takes as stream-json. Its last line
+  // is the same answer the plain call prints.
+  const files = messages.flatMap((m) => m.attachments ?? []);
+  const input = files.length
+    ? JSON.stringify({
+        type: "user",
+        message: {
+          role: "user",
+          content: [
+            { type: "text", text: transcript },
+            ...files.map((f) => ({
+              type: f.mediaType.startsWith("image/") ? "image" : "document",
+              source: { type: "base64", media_type: f.mediaType, data: f.data },
+            })),
+          ],
+        },
+      }) + "\n"
+    : transcript;
+  if (files.length) {
+    args.splice(args.indexOf("--output-format"), 2, "--input-format", "stream-json", "--output-format", "stream-json", "--verbose");
+  }
+
+  const { code, out, err } = await invoke(args, input, signal);
+  if (code !== 0) {
+    throw new Error(`Model call refused: claude exited ${code}: ${(err || out).slice(0, 500)}`);
+  }
+
+  let answer: CliAnswer;
+  try {
+    answer = JSON.parse(files.length ? out.trim().split("\n").pop()! : out) as CliAnswer;
+  } catch {
+    throw new Error(`Model call refused: claude did not answer with JSON: ${out.slice(0, 500)}`);
+  }
+  if (answer.is_error || typeof answer.result !== "string") {
+    throw new Error(`Model call refused: ${answer.subtype ?? "no result"}: ${String(answer.result ?? "").slice(0, 500)}`);
+  }
+
+  const { said, call } = tools?.length ? readReply(answer.result, tools) : { said: answer.result, call: undefined };
+  return {
+    text: said,
+    toolCalls: call ? [call] : [],
+    // What it would have cost on the API. A subscription is not billed per
+    // call, so this prices the run rather than charging it.
+    cost: answer.total_cost_usd ?? 0,
+    tokensIn: answer.usage?.input_tokens ?? 0,
+    tokensOut: answer.usage?.output_tokens ?? 0,
+  };
+}

package/model/memory.ts

@@ -0,0 +1,68 @@
+// The last few messages of one thread, and nothing else: no summarising and
+// nothing kept between threads. What an agent should remember across runs it
+// writes into its own folder, where it can be read and corrected.
+import { db } from "#chloe/core/db.ts";
+import type { Message } from "./model.ts";
+
+/** How many messages of a conversation a turn is shown, when the agent does not say. */
+export const RECALL = 10;
+
+export interface Used {
+  tool: string;
+  args: unknown;
+}
+
+/** Long strings in a call's arguments, like a whole file being written, are cut. */
+function clipArgs(args: unknown): unknown {
+  if (typeof args === "string") return args.length > 300 ? `${args.slice(0, 300)}...` : args;
+  if (Array.isArray(args)) return args.map(clipArgs);
+  if (args && typeof args === "object") return Object.fromEntries(Object.entries(args).map(([k, v]) => [k, clipArgs(v)]));
+  return args;
+}
+
+/** `used` is the tools a reply called, kept so a later turn can see how the reply was reached. */
+export function remember(thread: string, role: "user" | "assistant", content: string, used: Used[] = []): void {
+  if (!content) return;
+  db.prepare("insert into messages (thread, role, content, at, used) values (?, ?, ?, ?, ?)").run(
+    thread,
+    role,
+    content,
+    new Date().toISOString(),
+    used.length ? JSON.stringify(used.map((one) => ({ tool: one.tool, args: clipArgs(one.args) }))) : null,
+  );
+}
+
+/**
+ * The last `limit` messages of a thread, oldest first, leaving out any older
+ * than `days` when it is given. Nothing is deleted: a message too old to be
+ * recalled is still in the database and still on the page.
+ *
+ * With `tools`, a reply that called tools is preceded by those calls, in the
+ * same shape a turn's own calls take, with results that were not kept.
+ * Without them a model reading its own earlier answer cannot tell a fact it
+ * looked up from one it made up.
+ */
+export function recall(thread: string, { limit = RECALL, days, tools = false }: { limit?: number; days?: number; tools?: boolean } = {}): Message[] {
+  const since = days ? new Date(Date.now() - days * 86_400_000).toISOString() : "";
+  const rows = db
+    .prepare("select id, role, content, used from messages where thread = ? and at >= ? order by id desc limit ?")
+    .all(thread, since, limit) as { id: number; role: string; content: string; used: string | null }[];
+  return rows.reverse().flatMap((r): Message[] => {
+    const said: Message = { role: r.role as Message["role"], content: r.content };
+    if (!tools || !r.used) return [said];
+    const calls = (JSON.parse(r.used) as Used[]).map((one, i) => ({
+      id: `recalled-${r.id}-${i}`,
+      type: "function" as const,
+      function: { name: one.tool, arguments: JSON.stringify(one.args ?? {}) },
+    }));
+    return [
+      { role: "assistant", content: "", tool_calls: calls },
+      ...calls.map((call) => ({ role: "tool" as const, tool_call_id: call.id, content: "(done; the result was not kept)" })),
+      said,
+    ];
+  });
+}
+
+export function forget(thread: string): void {
+  db.prepare("delete from messages where thread = ?").run(thread);
+}

package/model/model.ts

@@ -0,0 +1,185 @@
+// Asking a model, two ways.
+//
+// A model is a string like "anthropic/claude-sonnet-5". By default it goes to
+// the Vercel AI Gateway over HTTP, so changing provider is changing that
+// string, and any gateway that speaks the same shape works by setting
+// AI_GATEWAY_URL.
+//
+// MODEL_VIA=claude sends it through the Claude Code CLI instead, which is the
+// only way to spend a Claude subscription: a subscription authorises the CLI
+// and is not an API key. See claude.ts. Everything above this file is the same
+// either way, which is the reason ask() is the only seam.
+
+import { setting, settings } from "#chloe/core/settings.ts";
+
+import { viaClaude } from "./claude.ts";
+
+/**
+ * Which way a model call goes. A box with a key uses it; a box with only a
+ * subscription falls through to the CLI, so a fresh clone runs either way
+ * without being told. MODEL_VIA settles it when both are there.
+ */
+export function via(): "gateway" | "claude" {
+  const chosen = setting(settings.model.via, "MODEL_VIA");
+  if (chosen === "gateway" || chosen === "claude") return chosen;
+  if (chosen) throw new Error(`model.via is ${JSON.stringify(chosen)}. It is "gateway" or "claude".`);
+  return gatewayKey() ? "gateway" : "claude";
+}
+
+function gatewayKey(): string {
+  return setting(settings.model.key, "AI_GATEWAY_API_KEY");
+}
+
+/** A file handed to the model with a message: a photo or a PDF. */
+export interface Attachment {
+  /** Like "image/jpeg" or "application/pdf". */
+  mediaType: string;
+  /** The file, base64. */
+  data: string;
+  name?: string;
+}
+
+/** In the shape the gateway wants it, apart from attachments, which each way turns into its own. */
+export interface Message {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  /** On a user message only. */
+  attachments?: Attachment[];
+  /** On an assistant message: the tools it asked for. */
+  tool_calls?: ToolCall[];
+  /** On a tool message: which call this answers. */
+  tool_call_id?: string;
+}
+
+export interface ToolCall {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+}
+
+export interface ToolSpec {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+export interface Answer {
+  text: string;
+  toolCalls: ToolCall[];
+  /** Dollars, when the gateway says. */
+  cost: number;
+  tokensIn: number;
+  tokensOut: number;
+}
+
+export interface Ask {
+  model: string;
+  messages: Message[];
+  tools?: ToolSpec[];
+  maxTokens?: number;
+  signal?: AbortSignal;
+}
+
+/** The chat-completions shape for a message with files: text first, then each file. */
+function forGateway({ attachments, ...message }: Message): unknown {
+  if (!attachments?.length) return message;
+  const url = (a: Attachment) => `data:${a.mediaType};base64,${a.data}`;
+  return {
+    ...message,
+    content: [
+      { type: "text", text: message.content },
+      ...attachments.map((a) =>
+        a.mediaType.startsWith("image/")
+          ? { type: "image_url", image_url: { url: url(a) } }
+          : { type: "file", file: { filename: a.name ?? "file", file_data: url(a) } },
+      ),
+    ],
+  };
+}
+
+/**
+ * Asks a model once and returns what it said, whichever way `model.via` sends
+ * it. The only seam between a key and a subscription.
+ */
+export function ask(request: Ask): Promise<Answer> {
+  return via() === "claude" ? viaClaude(request) : viaGateway(request);
+}
+
+async function viaGateway({ model, messages, tools, maxTokens, signal }: Ask): Promise<Answer> {
+  const key = gatewayKey();
+  if (!key) {
+    throw new Error(
+      "No gateway key. Put it in settings.local.json as model.key. " +
+        'To run on a Claude subscription instead, set model.via to "claude".',
+    );
+  }
+
+  const body = {
+    model,
+    messages: messages.map(forGateway),
+    max_tokens: maxTokens ?? 8000,
+    ...(tools?.length ? { tools: tools.map((t) => ({ type: "function", function: t })) } : {}),
+  };
+
+  let lastError = "";
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (attempt > 0) await wait(Math.min(2 ** attempt, 8) * 1000, signal);
+
+    const response = await fetch(setting(settings.model.gateway, "AI_GATEWAY_URL"), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: signal ?? AbortSignal.timeout(600_000),
+    }).catch((error: unknown) => error as Error);
+
+    if (response instanceof Error) {
+      lastError = response.message;
+      continue;
+    }
+    if (!response.ok) {
+      const text = (await response.text()).slice(0, 500);
+      // A bad key or a missing model fails the same way forever: say so now.
+      const worthRetrying = response.status === 408 || response.status === 409 || response.status === 429 || response.status >= 500;
+      lastError = `the gateway answered ${response.status}: ${text}`;
+      if (!worthRetrying) throw new Error(`Model call refused: ${lastError}`);
+      continue;
+    }
+
+    const json = (await response.json()) as GatewayAnswer;
+    const choice = json.choices?.[0];
+    if (!choice) {
+      lastError = "the gateway answered with no choices";
+      continue;
+    }
+    return {
+      text: choice.message?.content ?? "",
+      toolCalls: choice.message?.tool_calls ?? [],
+      // The gateway reports cost 0 for a user's own provider key and puts the
+      // real number in upstream_inference_cost.
+      cost: json.usage?.cost || json.usage?.cost_details?.upstream_inference_cost || 0,
+      tokensIn: json.usage?.prompt_tokens ?? 0,
+      tokensOut: json.usage?.completion_tokens ?? 0,
+    };
+  }
+  throw new Error(`Model call failed after 4 attempts: ${lastError}`);
+}
+
+interface GatewayAnswer {
+  choices?: { message?: { content?: string; tool_calls?: ToolCall[] } }[];
+  usage?: {
+    cost?: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    cost_details?: { upstream_inference_cost?: number };
+  };
+}
+
+function wait(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((done, fail) => {
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      fail(new Error("stopped"));
+    });
+  });
+}

package/model/tool.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+
+import type { ToolSpec } from "./model.ts";
+
+/**
+ * What a model can be handed: an id, a description a model reads, a schema for
+ * its arguments, and one function.
+ */
+export interface Tool<Input = any> {
+  id: string;
+  description: string;
+  inputSchema: z.ZodType<Input>;
+  execute: (input: Input) => Promise<unknown> | unknown;
+}
+
+/** The type of `execute`'s argument comes from the schema. */
+export function tool<Schema extends z.ZodType>(definition: {
+  id: string;
+  description: string;
+  inputSchema: Schema;
+  execute: (input: z.infer<Schema>) => Promise<unknown> | unknown;
+}): Tool<z.infer<Schema>> {
+  return definition as Tool<z.infer<Schema>>;
+}
+
+/** Keyed by the name the model calls them by. */
+export type Tools = Record<string, Tool>;
+
+/** One tool a model asked for: what it was called with, what came back, and whether it was allowed to run at all. */
+export interface Call {
+  tool: string;
+  args: unknown;
+  result: unknown;
+  /** Set when `approve` would not let it run, in which case nothing ran and `result` is what the model was told. */
+  refused?: boolean;
+}
+
+/**
+ * Asked before a tool runs, with the arguments the model chose. Return `true`
+ * to let it run. Anything else stops that one call, and a string is the reason
+ * the model is told, so do not answer "yes" when you mean true. Nothing runs
+ * while it is deciding, and what it decides is written into the run beside the
+ * call. It is your code, so throwing out of it fails the step rather than
+ * refusing the call.
+ */
+export type Approve = (call: { tool: string; args: unknown }) => Promise<boolean | string> | boolean | string;
+
+export function describe(name: string, one: Tool): ToolSpec {
+  const schema = z.toJSONSchema(one.inputSchema, { io: "input" }) as Record<string, any>;
+  // $schema means nothing to a provider and some reject it.
+  delete schema.$schema;
+  return { name, description: one.description, parameters: schema };
+}

package/model/tools/files.ts

@@ -0,0 +1,71 @@
+// The tools over do/files.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 { tool } from "#chloe/model/tool.ts";
+
+/**
+ * `what` names the folder in the tool's description, e.g. "the shared notes".
+ * `id` renames the tool, for an agent that binds two different folders and
+ * would otherwise have two tools called the same thing.
+ */
+interface Folder {
+  root: string;
+  what: string;
+  id?: string;
+}
+
+/** A tool that lists what is in one folder, and nothing outside it. */
+export function listIn({ 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),
+  });
+}
+
+/** A tool that reads one file inside that folder. */
+export function readIn({ 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),
+  });
+}
+
+/** A tool that searches the text of the files in that folder. */
+export function searchIn({ 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.`,
+    inputSchema: z.object({
+      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),
+  });
+}
+
+/** `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 }) {
+  return tool({
+    id,
+    description:
+      `Write one file in ${what}. This replaces the file, so include everything you want kept: ` +
+      `read it first unless it is new.` +
+      (commit ? " Committed as it is written, so `message` is required." : ""),
+    inputSchema: z.object({
+      path: z.string(),
+      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 }),
+  });
+}

package/model/tools/gmail.ts

@@ -0,0 +1,43 @@
+// The tool over do/mail.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 { tool } from "#chloe/model/tool.ts";
+
+interface Options {
+  /** Gmail query this agent may see, and nothing else. Set in its config. */
+  search: string;
+  /** How to describe that mail in the tool's description, in plain words. */
+  what: string;
+  /** Days back when the agent does not say. */
+  days?: number;
+  id?: string;
+}
+
+/**
+ * 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) {
+  return tool({
+    id,
+    description:
+      `Read ${what}. Lists what is there; pass a messageId from that list to read one in full. ` +
+      `You cannot change which mail this searches.`,
+    inputSchema: z.object({
+      days: z.number().int().min(1).max(30).optional().describe("How far back to look. Default 7."),
+      limit: z.number().int().min(1).max(25).optional().describe("How many at most. Default 10."),
+      messageId: z
+        .string()
+        .optional()
+        .describe("Read this one in full. Must be an id this tool already listed."),
+    }),
+    execute: ({ days: back, limit, messageId }) =>
+      messageId
+        ? oneMessage({ search, what, days: back ?? days, limit: limit ?? 10, messageId })
+        : messages({ search, days: back ?? days, limit: limit ?? 10 }),
+  });
+}