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/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.
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.
canReachfunction
export function canReach(address: string, agent = ""): booleanReturns 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.
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 forwriteFiles. 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.
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.
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 atag,[tag]is put in front of it.body: the text of the email. Plain text, or Markdown when the sender hasmarkdown: true.provider: the service that sends it,"resend"or"gmail". If not set, it usesemail.providerfrom 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).
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 gavesearchDriveFiles. 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.
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.
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 toroot.changes: each{ old, new }.oldis 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.newreplaces it, and an empty string deletes it.options:commit,message,authorandin, the same as forwriteFiles. 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.
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.
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.
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.
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 (seegitShows).
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.
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.
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.
isPrivatefunction
export function isPrivate(address: string): booleanTells 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.
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 fromfrom. 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.
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 insideroot, relative to it. If not set,rootitself.options.shows: when given, only what it shows is listed (seegitShows).
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.
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.
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.
markdownToHtmlfunction
export function markdownToHtml(markdown: string): stringTurns 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.
markdownToTextfunction
export function markdownToText(markdown: string): stringTurns 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.
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,authorandin, the same as forwriteFiles. 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.
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.
ownerfunction
export function owner(agent = ""): stringReturns 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.
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.
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.
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.
readAsTextfunction
export function readAsText(path: string, read: Awaited<ReturnType<typeof readFiles>>): stringWhat 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.
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 gavesearchDriveFiles. 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 listsearchDriveFilesreturned. 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.
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.
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 toroot. Its full path also works, if it is insideroot.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 neitherfromnorlines.options.shows: when given, a file it does not show is refused (seegitShows).
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.
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 gavereadEmailMessages. 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 listreadEmailMessagesreturned. Required.days,limit: used only when thissearchhas 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.
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 withhttp://orhttps://.from: where to start in the page's text, in characters. Default: 0. To read on, pass thenextof the lastPage.
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.
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.
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 thePATH) 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.
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 namelistScriptsreturns: a file in the agent'sscripts/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'sscripts/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.
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 filesearchmatches.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.
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 insideroot, to search only there. If not set, all ofroot.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 (seegitShows).
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: witharoundat 0, one line per match, aspath:line:text. Witharound, 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 witharound. Paths are relative toroot.note: set when nothing matched or when some matches were left out.
Throws if folder is outside root or does not exist.
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.
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().
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.
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.
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.
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.
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.
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.
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.
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 toroot.content: the text to write.options.append: addscontentto 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 whencommitistrue.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.