Chloe

Reference

@chloejs/core/services

The work a job does without asking anybody, called from a step.

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, listing its own runs, reading a web page, searching the web.

import { run, deliverEmail } 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.

addCalendarEventCalendarEventcanReachdeleteFilesdeliverdeliverEmaildownloadDriveFileDriveFileeditFilesEmailSenderfeedToTextfinishfolderTreeFoundhtmlToTextisPrivatelistCalendarEventslistFileslistScriptsMailmarkdownToHtmlmarkdownToTextmoveFilesNeedsClientownerownRunownRunsPagereadAsTextreadDriveFilereadEmailMessagesreadFilesreadOneEmailMessagereadPageResultrunrunScriptssearchDriveFilessearchFilessearchWebSendsendGmailsetupStepssignInStateSignInStatesplitstartStartedwriteFiles

addCalendarEventfunction

export async function addCalendarEvent({
  calendar = "primary",
  title,
  start,
  end,
  location,
  details,
}: {
  calendar?: string;
  title: string;
  start: string;
  end: string;
  location?: string;
  details?: string;
}): Promise<{ added: true; id: string; link: string }>

Adds one event to a Google calendar. Nobody is invited, so no email is sent to anyone.

  • calendar: the calendar's id. Default: "primary", the account's own calendar.
  • title: the event's title. Required.
  • start: when it starts. Required. Either a time with its offset, such as "2026-10-06T15:00:00-04:00", or a day, such as "2026-10-06", for an event that lasts all day.
  • end: when it ends, in the same form. Required. For an event that lasts all day, give the day after its last day.
  • location: where it is.
  • details: the event's description.

Returns { added: true, id, link }: the new event's id, and a link that opens it in Google Calendar.

Throws if start or end is not in one of those two forms, and nothing is added. Throws NeedsSignIn when someone has to sign in to Google, and an Error for any other problem with Google.

plugins/google/calendarService.ts:137

CalendarEventinterface

export interface CalendarEvent {
  /** The event's id in Google Calendar. */
  id: string;
  /** The id of the calendar it is on, such as `"primary"`. */
  calendar: string;
  /**
   * The event's title, or `(no title)`. Wrapped in
   * `<<<EXTERNAL_UNTRUSTED_CONTENT>>>` markers, because someone else may have
   * written it.
   */
  title: string;
  /**
   * When it starts: a time with its offset, such as
   * `2026-10-06T15:00:00-04:00`, or a day, such as `2026-10-06`, for an event
   * that lasts all day.
   */
  start: string;
  /**
   * When it ends, in the same form as `start`. For an event that lasts all
   * day, this is the day after its last day.
   */
  end: string;
  /** Where it is, if set. Wrapped in `<<<EXTERNAL_UNTRUSTED_CONTENT>>>` markers. */
  location?: string;
  /** The event's description, if set. Wrapped in `<<<EXTERNAL_UNTRUSTED_CONTENT>>>` markers. */
  details?: string;
  /** How many people are invited, the account itself included. Not set when nobody is invited. */
  people?: number;
  /** A link that opens the event in Google Calendar. */
  link?: string;
}

One event in the list listCalendarEvents returns.

plugins/google/calendarService.ts:28

canReachfunction

export function canReach(address: string, agent = ""): boolean

Returns true if a running channel can send to this address for this agent. It checks the channel part only, not that the person exists. Returns false for text that is not an address.

services/messageService.ts:67

deleteFilesfunction

export async function deleteFiles(root: string, path: string, options: CommitOptions = {})

Deletes a file, or a folder and everything in it, inside root.

  • options: the same as for writeFiles. Committed, the file is still in the history and can be brought back.

Returns { path }, the full path, and commit as writeFiles does.

Throws if path is outside root, is root itself, or is not there.

services/filesService.ts:386

deliverfunction

export async function deliver(address: string, text: string, agent = "", choices?: string[], multiple?: boolean): Promise<void>

Sends a message to an address, such as telegram:12345, through the channel running for that agent. Pass choices to show the possible answers as buttons, where the channel can, and multiple when several may be picked.

Throws if no running channel can reach the address. In a trial run it sends nothing, and the run's record keeps what it would have sent.

services/messageService.ts:84

deliverEmailfunction

export async function deliverEmail(
  { from, to, tag, replyTo, markdown }: EmailSender,
  subject: string,
  body: string,
  provider?: SendingProvider,
): Promise<{ sent: boolean; held?: true; id?: string; subject: string }>

Sends one email.

  • The first argument is an EmailSender: who it is from, who it goes to, and how it looks.
  • subject: the subject line. If the sender has a tag, [tag] is put in front of it.
  • body: the text of the email. Plain text, or Markdown when the sender has markdown: true.
  • provider: the service that sends it, "resend" or "gmail". If not set, it uses email.provider from the settings.

Returns { sent: true, id, subject }: the id the provider gave the email (if it gave one), and the subject as it was sent, with its tag.

When email.provider in the settings is "none", nothing is sent, even if you pass provider. The subject is only written to the log, and the result still says sent: true.

In a trial run nothing is sent either: the run's record keeps the email, and the result is { sent: false, held: true, subject }.

Throws if to is empty, or if the provider fails (for example: there is no Resend key, or nobody has signed in to Google).

services/emailService.ts:109

downloadDriveFilefunction

export async function downloadDriveFile({
  search = "",
  what,
  agent,
  file,
}: {
  search?: string;
  what: string;
  agent: string;
  file: string;
}): Promise<{ path: string; name: string; kind: string; bytes: number }>

Downloads one file from Google Drive as it is, such as a PDF or a picture, and saves it with the files people sent the agent (keepReceived), so a script can open it and it is deleted with them.

  • search: the same Drive search you gave searchDriveFiles. Default: "", all of Drive.
  • what: a short name for those files, used in the error message. Required.
  • agent: the agent's id, whose received files it goes in. Required.
  • file: a Drive link to the file, or its id. Required.

With a search, the file must be one searchDriveFiles listed with it. Without one, any file the signed-in account can open is in bounds, so a link the person sent works as it is.

Returns { path, name, kind, bytes }: the full path it was saved at, and its name, wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers.

Throws for a Google Doc, Sheet or Slides (read those with readDriveFile), for a file over 25 MB, NeedsSignIn when someone has to sign in to Google, and an Error for any other problem with Google.

plugins/google/driveService.ts:211

DriveFileinterface

export interface DriveFile {
  /** The file's id. Pass it to `readDriveFile` to read the file. */
  id: string;
  /**
   * The file's name. Wrapped in `<<<EXTERNAL_UNTRUSTED_CONTENT>>>` markers,
   * because someone else may have written it.
   */
  name: string;
  /**
   * The file's type, as Google writes it, such as
   * `"application/vnd.google-apps.document"` for a Google Doc, or
   * `"application/pdf"`.
   */
  kind: string;
  /** When the file was last changed, such as `"2026-10-06T19:00:00.000Z"`. */
  modified?: string;
  /** A link that opens the file in Google Drive. */
  link?: string;
}

One file in the list searchDriveFiles returns.

plugins/google/driveService.ts:27

editFilesfunction

export async function editFiles(
  root: string,
  path: string,
  changes: { old?: string; new: string }[],
  options: { commit?: boolean; message?: string; author?: string; in?: Place } = {},
)

Makes one or more changes to a file, and leaves the rest as it was. Each change replaces one piece of text, or with no old adds its text to the end of the file, or makes the file when it is not there. They are made in order, each on the file as the ones before it left it, and written once: if any cannot be made, none are.

  • root: the folder you allow. The file must be inside it.
  • path: the file, relative to root.
  • changes: each { old, new }. old is the text to replace, and must be in the file exactly once. When it is not there as written, it is looked for again with the spaces and tabs at the start and end of each line ignored, and that must find it once. new replaces it, and an empty string deletes it.
  • options: commit, message, author and in, the same as for writeFiles. All the changes are one commit.

Returns the same as writeFiles, plus lines: the line where each change starts, or 0 for text added to the end.

Throws if an old is not in the file, or is in it more than once (the message says which change, and how many times). Also throws if a change has an old and the file does not exist, and for the same reasons as writeFiles.

services/filesService.ts:443

EmailSenderinterface

export interface EmailSender {
  /**
   * The From line, such as `"Backups <info@example.com>"`. Required.
   *
   * With the `"gmail"` provider, Google only keeps an address that is the
   * signed-in account or an alias set up in Gmail. It sends anything else
   * from the signed-in account.
   */
  from: string;
  /** The addresses the email goes to. Required, with at least one address. */
  to: string[];
  /**
   * A word put in square brackets at the start of every subject, so you can
   * filter your inbox. With `"backups"`, the subject `Done` becomes
   * `[backups] Done`. Off by default.
   */
  tag?: string;
  /**
   * Where replies go. If not set, replies go to `from`. Set it when the `from`
   * address cannot receive mail.
   */
  replyTo?: string[];
  /**
   * Treats the body as Markdown. The email is sent as HTML (headings, lists,
   * tables, links), plus a plain text copy without the Markdown symbols.
   *
   * Off by default: the body is sent as plain text, exactly as written.
   */
  markdown?: boolean;
}

Who an email is from, who it goes to, and how it looks. You pass it to deliverEmail.

services/emailService.ts:20

feedToTextfunction

export function feedToText(xml: string, base: string): { title?: string; text: string }

Turns an RSS or Atom feed (a site's list of new posts) into readable text.

  • xml: the feed.
  • base: the feed's own address, used to turn relative links into full ones.

Each entry becomes its title as a link, then who wrote it and when, then its text. A blank line separates the entries.

Returns { title, text }: the feed's title, if it has one, and the entries. It does not throw.

plugins/web/webService.ts:234

finishfunction

export async function finish(answer: string): Promise<{ account: string; signedIn: true }>

Finishes the Google sign-in that start() began, and saves it.

  • answer: what the person sent back. Either the short code, or the whole address of the page their browser landed on.

Returns { account, signedIn: true }.

The person must approve with the same Google account as connections.google.account. Anyone with the link could approve with their own account, so a sign-in by any other account is thrown away.

Throws an Error, with words you can show the person, when:

  • no sign-in is waiting,
  • the answer is not a code or an address, or is from another sign-in,
  • Google does not accept the code (a code works once, for a few minutes),
  • someone approved with a different Google account,
  • the person unticked a box on Google's page, so a service is missing.

Most of these mean starting again with start(). Throws NeedsClient if there is no Google client.

plugins/google/googleService.ts:489

folderTreefunction

export async function folderTree(root: string, { depth = 2, most = 200, shows }: { depth?: number; most?: number; shows?: Shows } = {}): Promise<string[]>

Draws the folders inside root as lines of text, one folder per line. Each level down is indented two more spaces.

  • root: the folder to start from.
  • options.depth: how many levels down to go. Default: 2.
  • options.most: the most folders to show. Default: 200. If there are more, the last line is (more folders, left out).
  • options.shows: when given, only the folders it shows (see gitShows).

Files are left out, and so are hidden folders (starting with .) and secrets and node_modules.

Returns the lines, such as ["notes/", " 2026/", "projects/"]. A folder it cannot read is skipped, so it does not throw. If root does not exist, the list is empty.

services/filesService.ts:93

Foundinterface

export interface Found {
  title: string;
  /** The page's own address, to read with `readPage`. */
  url: string;
  /** A line or two from the page, as plain text. */
  snippet: string;
}

One result of searchWeb.

plugins/web/searchService.ts:11

htmlToTextfunction

export function htmlToText(html: string, base: string): { title?: string; text: string }

Turns HTML into readable plain text.

  • html: the HTML.
  • base: the page's own address, used to turn relative links into full ones.

It removes scripts, styles and the <head>. Paragraphs, rows and other blocks become lines, table cells are separated by |, and links become [text](url).

Returns { title, text }. title is the page's <title>, if it has one. It does not throw.

plugins/web/webService.ts:186

isPrivatefunction

export function isPrivate(address: string): boolean

Tells you whether an IP address is private, which means readPage will not read it.

  • address: an IP address, such as "10.0.0.1" or "::1". Not a name like "example.com".

Private means any address that is not on the public internet: this machine (such as 127.0.0.1), home and office networks (such as 192.168.1.5), and other reserved addresses, in IPv4 and IPv6. An IPv4 address written inside an IPv6 one is checked too.

Returns true if the address is private. Also returns true for anything that is not a valid IP address, names included.

plugins/web/webService.ts:70

listCalendarEventsfunction

export async function listCalendarEvents({
  calendars = ["primary"],
  from = new Date(),
  days = 7,
  limit = 50,
}: {
  calendars?: string[];
  from?: Date;
  days?: number;
  limit?: number;
}): Promise<{ from: string; to: string; events: CalendarEvent[] }>

Lists the events on one or more Google calendars, soonest first.

  • calendars: the ids of the calendars to read. "primary" is the account's own calendar. Default: ["primary"].
  • from: when to start looking. Default: now.
  • days: how many days to look ahead from from. Default: 7.
  • limit: the most events to return, across all the calendars. Default: 50.

Returns { from, to, events }: the start and end of the time it looked at, as text such as 2026-10-06T19:00:00.000Z, and the events. An event that repeats is listed once for each time it happens.

Throws NeedsSignIn when someone has to sign in to Google. Throws an Error for any other problem with Google, such as a calendar id that does not exist.

plugins/google/calendarService.ts:76

listFilesfunction

export async function listFiles(root: string, path?: string, { shows }: { shows?: Shows } = {})

Lists what is in one folder.

  • root: the folder you allow. Nothing outside it can be listed.
  • path: a folder inside root, relative to it. If not set, root itself.
  • options.shows: when given, only what it shows is listed (see gitShows).

Returns { path, entries }: the full path of the folder it listed, and the names in it, sorted. A folder's name ends with /. Hidden names (starting with .), the folders no file tool may open and the state folder are left out.

Throws if path is outside root, goes into .git, .ssh, secrets or node_modules, or does not exist.

services/filesService.ts:64

listScriptsfunction

export async function listScripts(agent: string): Promise<string[]>

Lists an agent's scripts: the files in its scripts/ folder, and the executable files inside its skill folders as <skill folder>/<file>.

  • agent: the agent's id.

Returns the names runScripts takes. The list is empty if the agent has neither. Throws if no agent with this id has been loaded.

services/scriptsService.ts:57

Mailinterface

export interface Message {
  /** The email's id. Pass it to `readOneEmailMessage` to read the whole email. */
  id: string;
  /** The id of the conversation (thread) the email is in. */
  threadId?: string;
  /** The subject line. */
  subject?: string;
  /** The sender, as the From line writes it, such as `Ana <ana@example.com>`. */
  from?: string;
  /** When it was sent, as the Date line writes it, such as `Tue, 6 Oct 2026 09:12:00 -0400`. */
  date?: string;
  /** The first words of the email, as Gmail shows them in a list. */
  snippet?: string;
}

One email in the list readEmailMessages returns.

subject, from and snippet come wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers, because someone else wrote them.

plugins/google/gmailService.ts:33

markdownToHtmlfunction

export function markdownToHtml(markdown: string): string

Turns Markdown into HTML for an email, with simple styles that mail apps show.

  • markdown: the Markdown text.

It understands # headings, - and * lists, | tables, > quotes, code blocks between ``` lines, **bold**, `code`, [words](address) links and plain web addresses. A link works only for http:, https: and mailto: addresses. Any other link becomes plain words.

Lines next to each other join into one paragraph. Only a blank line starts a new paragraph, so text wrapped at any width still reads as normal sentences.

Returns the HTML as one string. It does not throw.

services/emailService.ts:166

markdownToTextfunction

export function markdownToText(markdown: string): string

Turns Markdown into plain text for an email.

  • markdown: the Markdown text.

It removes #, ** and backticks. A table row becomes a: b, and a link becomes words (address). Returns the text. It does not throw.

services/emailService.ts:243

moveFilesfunction

export async function moveFiles(root: string, path: string, to: string, options: CommitOptions = {})

Moves or renames a file or a folder inside root, making the folders above to when they are not there.

  • options: commit, message, author and in, the same as for writeFiles. Both places are one commit, so a file changed without a commit and then moved is committed with the move.

Returns { path, to }, both full paths, and commit as writeFiles does.

Throws if either is outside root or is root itself, if path is not there, or if to already is.

services/filesService.ts:356

NeedsClientclass

export class NeedsClient extends Error {

Thrown when chloe has no Google client to sign in with.

A client is an id and a secret that you make once in Google's console, so chloe can ask Google for a sign-in. A person has to make it, and put it in connections.google.client in the settings. setupSteps() returns the steps to show them.

plugins/google/googleService.ts:125

ownerfunction

export function owner(agent = ""): string

Returns the address of the agent's owner, such as telegram:12345. A job's questions and approvals go to this person when no one else is named.

It is owner in settings, if set. If not, it is the first id in allowFrom of the agent's Telegram, Slack, Discord or WhatsApp channel. Returns "" if there is neither.

services/messageService.ts:130

ownRunfunction

export function ownRun(agent: string, id: string)

One of the agent's runs in full: what started it, what it answered or why it failed, and its steps in order, each cut to a length a model can read.

services/selfService.ts:169

ownRunsfunction

export function ownRuns(agent: string, options: { job?: string; limit?: number } = {})

The agent's runs, newest first: the facts of each and none of its words, so nothing in the list came from outside. job keeps to one job, "chat" to conversations.

services/selfService.ts:138

Pageinterface

export interface Page {
  /** The page's address, after any redirects. */
  url: string;
  /** The HTTP status code the site answered with, such as `200`. A `404` page that is text is still returned. */
  status: number;
  /** The page's title, if it has one. */
  title?: string;
  /** This part of the page as plain text, up to 20,000 characters. Links on an HTML page are written as `[text](url)`. */
  text: string;
  /** Where the next part starts, if there is more. Pass it as `from` to `readPage` to read on. Not set on the last part. */
  next?: number;
}

A web page that readPage read as text. A long page comes in parts, one part per call.

plugins/web/webService.ts:15

readAsTextfunction

export function readAsText(path: string, read: Awaited<ReturnType<typeof readFiles>>): string

What readFiles returned, as a model is shown it: a line with path and which of its lines these are, the note when there is more, then the text just as it is in the file. Shown as JSON, every line break and quote comes escaped, and a model copying text back out of it for a change gets the spaces wrong.

services/filesService.ts:186

readDriveFilefunction

export async function readDriveFile({
  search = "",
  what,
  fileId,
}: {
  search?: string;
  what: string;
  fileId: string;
}): Promise<{ id: string; name: string; kind: string; text: string; cut: boolean }>

Reads one file from Google Drive as text.

A Google Doc or Slides is read as plain text, and a Google Sheet as CSV (comma-separated values). Any other file is read only if it is already text, such as .txt, .md, .csv or .json.

  • search: the same Drive search you gave searchDriveFiles. Default: "".
  • what: a short name for those files, used in the error message, such as "the reports folder". Required.
  • fileId: the file's id, from the list searchDriveFiles returned. Required.

Returns { id, name, kind, text, cut }. name and text are wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers, because someone else wrote them. Only the first 200,000 characters are read, and cut is true when the file was longer.

Throws if searchDriveFiles has not listed this file with the same search since chloe started, or if the file is not text (such as a picture or a PDF). Throws NeedsSignIn when someone has to sign in to Google, and an Error for any other problem with Google.

plugins/google/driveService.ts:153

readEmailMessagesfunction

export async function readEmailMessages({
  search,
  days = 7,
  limit = 10,
}: {
  search: string;
  days?: number;
  limit?: number;
}): Promise<{ query: string; count: number; messages: Message[] }>

Lists recent emails that match a Gmail search.

  • search: the search, written as in Gmail's search box, such as "in:inbox" or "from:alerts@example.com". Required.
  • days: how many days back to look. Default: 7.
  • limit: the most emails to return. Default: 10.

Returns { query, count, messages }: the search that ran (your search plus newer_than:<days>d), how many emails it found, and the emails. Each email's subject, from and snippet come wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers, because someone else wrote them.

readOneEmailMessage only reads emails that a search with the same search listed. So write search in your code, not from text a model or an email gave you.

Throws NeedsSignIn when someone has to sign in to Google (nobody has yet, or the sign-in expired). Throws an Error for any other problem with Google.

plugins/google/gmailService.ts:144

readFilesfunction

export async function readFiles(
  root: string,
  path: string,
  { from, lines, limit, shows }: { from?: number; lines?: number; limit?: number; shows?: Shows } = {},
)

Reads one text file.

  • root: the folder you allow. The file must be inside it.
  • path: the file, relative to root. Its full path also works, if it is inside root.
  • options.from: the first line to read, counting from 1.
  • options.lines: how many lines to read.
  • options.limit: the most characters to return, when you give neither from nor lines.
  • options.shows: when given, a file it does not show is refused (see gitShows).

With no options, it returns the whole file as { path, bytes, content }: the full path, the file's length in characters, and its text.

With from or lines, content holds only those lines. The result also has totalLines, and from and to (the first and last line returned). With limit, a longer file is cut at the last whole line that fits. In both cases, note says when there is more to read.

Throws if path is outside root, goes into .git, .ssh, secrets or node_modules, or does not exist.

services/filesService.ts:137

readOneEmailMessagefunction

export async function readOneEmailMessage({
  search,
  what,
  days = 7,
  limit = 10,
  messageId,
}: {
  search: string;
  what: string;
  days?: number;
  limit?: number;
  messageId: string;
}): Promise<{ query: string; message: unknown }>

Reads one whole email.

  • search: the same Gmail search you gave readEmailMessages. Required.
  • what: a short name for those emails, used in the error message, such as "the backup alerts". Required.
  • messageId: the email's id, from the list readEmailMessages returned. Required.
  • days, limit: used only when this search has not listed the id since chloe started. Then the search runs again with them, and the email is read only if it is in the list. Default: 7 and 10.

Returns { query, message }. message has id, threadId, date, from, to, subject, labels, attachments (the file names) and body (the plain text; for an email with only HTML, the HTML without its tags). from, to, subject and body come wrapped in <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers, because someone else wrote them.

Throws if the email is not one this search lists, so a wrong or made-up id cannot read other mail. Throws NeedsSignIn when someone has to sign in to Google, and an Error for any other problem with Google.

plugins/google/gmailService.ts:219

readPagefunction

export async function readPage(address: string, from = 0): Promise<Page>

Reads a web page and returns it as plain text, 20,000 characters at a time. A page that answered 400 or more comes back as its first 1,000 only.

  • address: the full web address, starting with http:// or https://.
  • from: where to start in the page's text, in characters. Default: 0. To read on, pass the next of the last Page.

An HTML page becomes readable text, with links kept as [text](url). An RSS or Atom feed becomes a list of its entries. Plain text, JSON and other XML come back as they are. Each call reads the whole page again.

It only reads public addresses. It refuses this machine, home and office networks and other private addresses (see isPrivate), and checks each redirect the same way. If the site answers "too many requests" (429), it waits 30 to 60 seconds and tries once more.

Returns a Page.

Throws if the address is not valid or not http or https, if it is private, or if the page:

  • takes more than 30 seconds to answer,
  • is larger than 5 MB,
  • is not text (such as an image or a PDF),
  • redirects more than 5 times,
  • answers 429 twice.

plugins/web/webService.ts:282

Resultinterface

export interface Result {
  /**
   * The program's exit code. `0` means it worked.
   *
   * `127` means the program was not found. `1` is also used when the program
   * could not start, or was stopped because it ran too long.
   */
  exitCode: number;
  /** What the program printed. Cut after 80,000 characters. */
  stdout: string;
  /** What the program printed as errors. Cut after 80,000 characters. */
  stderr: string;
}

What run returns when a program has finished.

services/runService.ts:8

runfunction

export function run(
  file: string,
  args: string[],
  options: { timeoutMs?: number; cwd?: string; env?: Record<string, string>; signal?: AbortSignal } = {},
): Promise<Result>

Runs one program on this machine and waits for it to finish.

  • file: the program, by name (found on the PATH) or by full path.
  • args: the program's arguments, one string each.
  • options.timeoutMs: how long it may run, in milliseconds. Default: 60000 (one minute).
  • options.cwd: the folder it runs in. Default: the folder chloe runs in.
  • options.env: extra environment variables. The program also gets all of chloe's own.
  • options.signal: stops it, the way the time limit does, when it fires.

It never uses a shell. Each argument reaches the program exactly as you wrote it, so text from a model or a person cannot start a second command.

Returns a Result. It does not throw when the program fails: check exitCode. Each output is cut after 80,000 characters.

services/runService.ts:46

runScriptsfunction

export async function runScripts(
  agent: string,
  name: string,
  args: string[] = [],
  { timeoutMs = 300_000, cwd, signal }: { timeoutMs?: number; cwd?: string; signal?: AbortSignal } = {},
): Promise<Result & { script: string; args: string[] }>

Runs one of an agent's scripts and waits for it to finish.

  • agent: the agent's id.
  • name: a name listScripts returns: a file in the agent's scripts/ folder, such as "backup.sh", or one inside a skill folder, such as "fill-pdfs/scripts/fill.py". So it cannot be a path to anything else.
  • args: the script's arguments, one string each. They reach the script exactly as written, never through a shell. Default: none.
  • options.timeoutMs: how long it may run, in milliseconds. Default: 300000 (five minutes).
  • options.cwd: the folder it runs in. Default: the agent's scripts/ folder, or for a skill's script that skill's folder, so the script can use paths relative to it.
  • options.signal: stops the script when it fires, as the time limit does. Default: none.

The script file must be executable, with a first line such as #!/bin/sh. It gets chloe's environment variables, plus MEMORY_FOLDER (the agent's memory folder).

Returns a Result, plus script and args. It does not throw when the script fails: check exitCode.

Throws if the agent has no script with this name, or if no agent with this id has been loaded.

services/scriptsService.ts:81

searchDriveFilesfunction

export async function searchDriveFiles({
  search = "",
  text,
  limit = 20,
}: {
  search?: string;
  text?: string;
  limit?: number;
}): Promise<{ count: number; files: DriveFile[] }>

Finds files in Google Drive. Files in the trash are left out.

  • search: a search in Drive's own search language that sets which files can be found, such as "'<folder id>' in parents" for the files in one folder. Default: "", every file the account can open.
  • text: words to look for in the files' names and contents. If not set, every file search matches.
  • limit: the most files to return. Default: 20.

Returns { count, files }. Without text, the files changed most recently come first.

readDriveFile only reads files that a search with the same search listed. So write search in your code, not from text a model gave you.

Throws NeedsSignIn when someone has to sign in to Google. Throws an Error for any other problem with Google, such as a search that Drive cannot read.

plugins/google/driveService.ts:84

searchFilesfunction

export async function searchFiles(root: string, query: string, folder?: string, { around = 0, shows }: { around?: number; shows?: Shows } = {})

Searches the text files in a folder for some words.

  • root: the folder you allow. Nothing outside it is searched.
  • query: the words to find. Upper and lower case are the same, and the words are matched exactly as written (not as a pattern).
  • folder: a folder or one file inside root, to search only there. If not set, all of root.
  • options.around: how many lines before and after each match to show. Default: 0.
  • options.shows: when given, only the files it shows are searched (see gitShows).

It looks in every file and folder inside, hidden ones too, except .git, .ssh, secrets and node_modules. It skips files that are not text and files over 20 MB. It finds at most 5 matches in each file.

Returns { matches, results, note }:

  • matches: how many matches it found.
  • results: with around at 0, one line per match, as path:line:text. With around, one block of text for each group of nearby matches, with line numbers, and > on the lines that matched. At most 80 matches, or 30 with around. Paths are relative to root.
  • note: set when nothing matched or when some matches were left out.

Throws if folder is outside root or does not exist.

services/filesService.ts:213

searchWebfunction

export async function searchWeb(query: string, count = 10): Promise<Found[]>

Searches the web and returns up to count results (default 10, at most 20), each a title, an address and a line from the page.

Goes to Brave Search when connections.brave.api_key is set, and otherwise to DuckDuckGo, which needs no key but is a page for people rather than an API: it can refuse a machine that searches often. Throws when the service refuses, never returns an empty list for it.

plugins/web/searchService.ts:65

Sendtype

export type Send = (to: string, text: string, choices?: string[], multiple?: boolean) => Promise<void>;

A function that sends a message to one person on a channel.

to is the part of the address after the :, such as 12345 in telegram:12345. choices lists the possible answers when there are only a few, so the channel can show them as buttons. With multiple, the person may pick several, and sends them as one message with together().

services/messageService.ts:23

sendGmailfunction

export async function sendGmail({
  to,
  subject,
  text,
  html,
  replyTo,
  from,
}: {
  to: string[];
  subject: string;
  text: string;
  html?: string;
  replyTo?: string[];
  /**
   * The From line. Google only keeps an address that is the signed-in account
   * or an alias set up in Gmail. It sends anything else from the signed-in
   * account.
   */
  from?: string;
}): Promise<{ id: string }>

Sends one email from the Google account chloe is signed in to. It comes from that account's own address, and replies go to that account's inbox. deliverEmail calls this when email.provider is "gmail".

  • to: the addresses it goes to. Required.
  • subject: the subject line. Required.
  • text: the body as plain text. Required.
  • html: the body as HTML. If set, the email holds both, and the mail app picks one.
  • replyTo: where replies go. If not set, replies go to the sender.
  • from: the From line. If not set, the signed-in account.

Returns { id }, the id Gmail gave the sent email. In a trial run nothing is sent, the run's record keeps the email, and id is "".

Throws if from, to, replyTo or subject has a line break in it, and nothing is sent. Throws NeedsSignIn when someone has to sign in to Google, and an Error for any other problem with Google.

plugins/google/gmailService.ts:298

setupStepsfunction

export function setupSteps(): { steps: string[]; addresses: string[]; why: string }

Returns the steps to make a Google client in Google's console. A person follows them once. Show them when NeedsClient is thrown, or when connections.google.client is not set. Takes nothing.

Every copy of chloe needs its own client, because Google treats reading Gmail as its most sensitive kind of access.

Returns:

  • why: a sentence on why the steps are needed.
  • steps: the steps in Google's console, in order, in plain words. Where the file goes after them is the caller's to say: a chat and the page say it differently.
  • addresses: the addresses Google may send the person back to after they approve. The steps say to add them to the client, exactly as written.

plugins/google/googleService.ts:643

signInStatefunction

export async function signInState(): Promise<SignInState>

Tells you where the Google sign-in stands: whether it is ready, and if not, what is missing. Takes nothing.

It only reads chloe's own files and never calls Google, so it is fast. A job can call it before it reads mail. Because it does not ask Google, it cannot see a sign-in that Google has cancelled.

Returns a SignInState. A problem is put in missing, not thrown.

plugins/google/googleService.ts:315

SignInStateinterface

export interface SignInState {
  /**
   * `true` when chloe has a saved sign-in for this account that can reach
   * Gmail, Calendar and Drive. Google is not asked, so a sign-in that Google
   * has cancelled can still show `true`.
   */
  ready: boolean;
  /** The Google account from `connections.google.account` in the settings. Empty if it is not set. */
  account: string;
  /** What is missing, in plain words you can show a person. Empty when nothing is. */
  missing: string;
  /** `true` when a sign-in was started and its code has not come back yet. */
  waiting: boolean;
}

Where the Google sign-in stands. signInState() returns it.

plugins/google/googleService.ts:150

splitfunction

export function split(address: string): { channel: string; to: string }

Splits an address such as telegram:12345 into its two parts: { channel: "telegram", to: "12345" }. Throws if the text is not an address.

services/messageService.ts:54

startfunction

export async function start({ services = SERVICES }: { services?: string } = {}): Promise<Started>

Starts a Google sign-in for the account in connections.google.account. Returns a link for the person to open and approve.

  • services: the Google services to ask for, separated by commas. Default: "gmail,calendar,drive". Keep the default: chloe only counts a sign-in as ready when it has all three.

Send the person say and link. They send back a short code, or the address of the page their browser landed on. Pass that to finish().

The started sign-in is saved in a file, so chloe can restart, or a job can wait a day, before finish(). Starting a new one replaces the one that was waiting.

Throws NeedsClient if there is no Google client. Throws an Error if connections.google.account is not set, if the client cannot be read, or if services names a service that does not exist.

plugins/google/googleService.ts:375

Startedinterface

export interface Started {
  /** The link the person opens to approve the sign-in. Send it exactly as it is: a changed link fails. */
  link: string;
  /** The Google account the sign-in is for, from `connections.google.account`. */
  account: string;
  /** What to tell the person, in plain words. It matches how this sign-in will finish. */
  say: string;
}

What start() returns.

plugins/google/googleService.ts:341

writeFilesfunction

export async function writeFiles(
  root: string,
  path: string,
  content: string,
  {
    commit = false,
    message,
    append = false,
    author,
    in: place,
  }: { commit?: boolean; message?: string; append?: boolean; author?: string; in?: Place } = {},
)

Writes one text file, and makes any folders it needs.

  • root: the folder you allow. The file must be inside it.
  • path: the file, relative to root.
  • content: the text to write.
  • options.append: adds content to the end of the file, on a new line, instead of replacing the file. Off by default.
  • options.commit: saves the change as a git commit of this one file. Other changes in the repository stay as they were. Off by default.
  • options.message: the commit message, at least 10 characters. Required when commit is true.
  • options.author: the name the commit is made under, usually the agent's id. If not set, the git user set on this machine.
  • options.in: "memory" if the file is in the agent's memory, "folder" if it is in the agent's own folder. If set, and a run is going, the run's record lists the commit.

Returns { path, bytes }: the full path, and the length of content in characters. With commit, it also has commit: the commit's id, or words saying why nothing was committed (for example, root is not in a git repository). A commit that fails does not throw: the file is still written.

Throws if path is outside root or goes into .git, .ssh, secrets or node_modules, or if commit is true and message is shorter than 10 characters.

services/filesService.ts:317