For assistants
Writing a task for Faber.
Everything needed to write a task's code and hand it to Faber with submit_task_source. Faber checks the code, sets the task up, then reads it back and writes the task's instructions from what the code actually does, so the person approves a description that matches behavior they cannot read.
What belongs here
Faber is for work that writes to a third-party account, needs a condition checked before a write, or has to recur after this conversation ends. A reminder with nothing to read and nothing to write belongs in your own scheduler. A one-off draft or summary belongs in the chat.
Check browse_task_catalog first. If the catalog already has this task, install_task gives the person the tested version, and writing a copy loses that.
The four files
A submission carries these and nothing else. You declare the whole program; Faber checks what arrives and, if it passes, connects it to the person's accounts and previews it.
main.ts. The program. Required. It exports a default async function and imports fromfaber-connectors.spec.md. What the program does, in the person's own words. Required. This is what they approve, because they cannot read the code. Write it for them, not for a reviewer: what it looks at, what it sends or changes, when it runs, what it skips, and any value fixed in the code that they might expect to be able to change. Faber checks it against the program before anything is created, and a claim the code does not support is refused. Do not write a first line about where the description came from: Faber adds that line itself, and aspec.mdthat arrives carrying it is refused.manifest.json. Onlyname,settings,inputsandtimeout.settingsis where every value a non-technical person might change belongs, with its default: every key the code reads withgetSetting,getSettingList,getSettingNumber,getSettingDictorgetSecretmust be declared here, and a key the code reads that the manifest does not declare is refused. Faber works outconnectors,allow_net,force_live_stepsandrequested_approval_stepsfrom the code, and drops them if you send them: a shipped copy is stale the moment the code changes. In particularallow_netgrants nothing on its own. Network access comes from importing thehttpconnector, and the runtime never readsmain.tsto widen permissions.approval_rules.json. One entry per write that should wait for the person, keyed by that write's label.main.tscontains nothing about approval. A rule can only ADD a hold: it can never release one the person set.
setup.ts is refused, for now. Inline scripts still run in the same process as the connectors, so a derivation script from an outside author is not isolated yet.
build_requirements.md is refused. It is Faber's own note of a target it derived from a conversation, and there is no conversation here: your code is the target and your spec.md is what it is checked against.
The start
The start is not in the files. Pass it as start on submit_task_source, and it is set before the build runs:
// start, a schedule
{ "kind": "schedule", "frequency": "weekly", "time": "08:00", "days": ["mon"] }
// frequency: "daily" | "weekly" | "monthly"; time is HH:MM in the person's
// own timezone, which Faber knows; days for weekly ("mon".."sun");
// day_of_month for monthly.
// start, a trigger: the run starts when mail arrives that matches
{ "kind": "new_email", "senders": ["@acme.com"], "attachment": true }
// senders / recipients: address fragments, any matches; keywords: words in the
// subject or body; attachment: only mail with a file attached; direction:
// "received" (default) or "sent".Leave start out and Faber sets the one the code implies. A program that starts on a trigger reads what started it with the reader the connector reference names (getNewEmailTrigger(), getTrackerItemTrigger()); each returns undefined when the run was started any other way, so check for that before reading it.
Writes and approval
Every write takes a label. It is that write's identity: the person sees it, an approval rule is keyed to it, and renaming it strands the rule. Give each write a distinct one.
// approval_rules.json
[
{
"key": "send_the_invoice_reminder",
"label": "Send the invoice reminder",
"hold": "when",
"body": "return (sent as { amount: number }).amount > 5000;",
"approval_rule": "the amount is over your limit"
}
]
// "key" is the label's slug: lowercased, and every run of characters that are
// not letters or digits becomes one "_". A rule whose key is anything else
// matches no write and holds nothing.
// "body" is the body of a function of one argument, "sent", typed unknown: the
// write's own payload, which is the options the write was called with, minus
// the label. A batch write (records, rows, messages) hands the rule ONE item at
// a time, so the body sees one record, not the list. A body that throws holds
// the write.
// The rule sees what the write SENDS. An update sends the fields it changes, so
// a condition about a column the write leaves alone needs that column put in the
// payload: to hold on a proposal's Value while writing Status, send both. Faber
// previews every rule against real rows and refuses one that reads a field no
// row had, so a rule written against the wrong shape fails the build rather than
// shipping and never matching.
// "hold" is one of:
// "never" registered, holds nothing by itself (the person can still turn it on)
// "always" waits every run, every item
// "when" waits when the write's own payload matches "body"The runtime
What faber-connectors exports besides the connectors. These are the shapes the type check holds a submission to.
import { email, sheets, sheetsFile, pages, result } from "faber-connectors";
// A picked setting: the person chooses the spreadsheet at setup. Never an id.
const clientList = sheetsFile({
label: "Client list",
description: "The spreadsheet with a Clients tab and a Waiting on me tab",
});
export default async function () {
const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
const rows: string[][] = [];
for await (
const batch of pages((cursor) =>
email.listMessages({ after: since, excludeMailingList: true, limit: 100, cursor })
)
) {
for (const m of batch) rows.push([m.from, m.subject, m.date.slice(0, 10)]);
}
if (rows.length > 0) {
await sheets.appendRows({
label: "Add the unanswered client threads", // the write's identity
file: clientList,
range: "Waiting on me!A:C",
values: rows,
});
}
result({ summary: `${rows.length} thread(s) added.`, rows });
}// Output. JSON only: string | number | boolean | null | FileRef, and objects
// and arrays of those. A TypeScript `interface` is not assignable to it;
// use a `type` alias or a plain object literal.
result(value: ResultValue): void
// A file the run produced: goes to a write that takes a FileRef (files.upload,
// an email attachment) or into result(). Async, three positional arguments.
await file(name: string, content: Uint8Array | string, mimeType: string): Promise<FileRef>
// The body of anything that sends a document (faberMail.send, email.sendMessage,
// notify.post's content): a string, a node, or a list of either, nested.
type Content = string | ContentNode | Content[];
interface ContentNode {
text?: Content; bold?: boolean; italics?: boolean; heading?: 1 | 2 | 3 | 4 | 5 | 6;
link?: string; // makes the text a link
ul?: Content[]; ol?: Content[];
table?: { rows: Content[][]; headerRows?: number }; // headerRows defaults to 1
code?: string; divider?: boolean; image?: string | FileRef; width?: number;
}
// Settings the manifest declares. Every declared setting has a value at run
// time; an unset one reads "". Give a number setting a default.
getSetting(key: string): string
getSettingNumber(key: string): number
// The person's timezone name ("America/Los_Angeles"). Dates in are Date
// instants, dates out are ISO 8601 strings, on every connector.
getTimezone(): string
// Reporting dates follow the saved schedule, including preview and manual runs.
// Previous completed day, Monday–Sunday week, or calendar month vs its predecessor.
// Manual-only defaults weekly; hourly refreshes yesterday. Freshness never shifts dates.
// Pass the provider reporting zone (Search Console: America/Los_Angeles; ads: account zone).
reportPeriods(options?: { now?: Date; timezone?: string }): { cadence: "daily" | "weekly" | "monthly"; timezone: string; period: { startDate: string; endDate: string }; before: { startDate: string; endDate: string } }
// Walk every page of a list read. `pages` when the loop leaves the match set
// alone; `drain` when each write removes what it read (archive, move, trash).
for await (const batch of pages((cursor) => x.list({ ..., cursor }))) { ... }
await drain(() => x.list({ ... }), (batch) => x.archiveMessages({ messages: batch }))
// What started a triggered run, or undefined when the run was started another way.
getNewEmailTrigger(): { messageId: string; threadId?: string; from?: string; subject?: string; ... } | undefined
getTrackerItemTrigger(): { destination; destinationName; to; item } | undefinedWhat the check refuses
The submission runs the same deterministic rules the build runs, in this order, and stops at the first. Nothing is created until all pass, and a refused submission leaves nothing behind: fix what the findings name and call submit_task_source again.
main.tscompares the run mode to a literal. Reads run live and writes are captured in a preview by the runtime, so a task never detects the mode.main.tssingles out the example event a preview is run against. It is delivered like a real one and must be treated as one.- No default export. The runtime invokes
export default async function; a namedrun()is never called. - An
ai.*call without alabelin its second argument, or whosepromptis not one text literal. The person reads and can replace the prompt, so everything that varies goes indata, not in the string. - A picker (
sheetsFile,notifyDestination,notionDatabaseand the rest) without alabeland adescription, or two with the same label. - A write without a
label, with a label that is not one plain string literal (no${...}), or two writes sharing one. - A
memory.*declaration without alabel.
Then the type check against the connector reference; then the program is refused if it neither writes nor calls result(); then every setting the code reads must be declared in manifest.json; then every rule in approval_rules.json must key a write the program has.
Then a reviewer reads main.ts against your spec.md and asks one question: does the code do what the description says? A contradiction is refused and named. Everything else it notices comes back as an advisory finding beside the lint ones, for you to take or leave. The program is yours, and a reviewer's preference is not a defect.
Last, every connector the program imports must have a connected account, and the finding names which to connect. That one is not a code fix: hand the person the link, and submit the same code again once they have used it.
Previews
A preview runs the program with every write captured and discarded, and it is what the person sees before they approve anything. Two things are worth knowing while you write:
- A program that writes nothing and calls no
result()is refused, because its preview would show the person nothing. http.fetchdecides read from write by the HTTP verb alone, and reads run live even in a preview. AGETwith side effects will reach the world during a preview. Use a write verb for anything that changes something.
Connectors
Import only from faber-connectors. Every connector below is one a submitted task may import. A few are imported under a different identifier than the name they are listed under here (google-sheets is googleSheets), and the reference tells you which.
The API is not on this page. Call the get_connector_docs MCP tool with the connectors this task will import, and it returns what each one does, its type signatures and the notes on using it. Either name works. That is the same reference Faber's own builder is given for the connectors a build declares, so your code and Faber's are written against one document.
ads | Read what an ad platform's own reporting says an account got for its money: spend, impressions, clicks and results, by campaign, ad set or ad, over a window. Meta today, and a task never names it for reporting. The connector also exposes explicit Meta-only CRM outcome and customer-list audience methods. Those writes never change campaigns or budgets, and preview always simulates them rather than sending anything to Meta. |
|---|---|
ai | Analyze content, generate text, or produce structured JSON via the user's configured AI model. Use only for work that deterministic code can't handle. |
airtable | Read and write Airtable records over its Web API: list bases and table schemas, read/filter/search records, create/update/upsert/delete them, and read and post record comments. |
archive | List and extract ZIP, TAR, gzip, and tar.gz files. |
banking | Reads the bank account the user connected: balances, the transactions in and out of it, and its statements. Mercury today; the same code runs against the others as they are added, so a task never names a bank. |
bitrix24 | Read and write leads, deals, contacts, and companies in the task's selected Bitrix24 workspace. The account is bound by Faber; task code never handles credentials, workspace URLs, or member IDs. Writes are simulated during preview and never touch the workspace until a live run. |
calendar | Read and manage calendar events, respond to invitations, and find time when everyone is free. One connector over Google Calendar and Outlook Calendar; the calendar is whichever account the task is bound to. |
chat | Read the conversations the user is in and answer in them, over Slack or Microsoft Teams. One connector over both; the account is a setting the user fills in. |
crm | Find and update leads, contacts, companies, and deals in the CRM account selected for the task. The same task works with HubSpot, Bitrix24, or Pipedrive. Provider-only entities and operations remain on the provider connector. |
csv | Parse, read, and create CSV files. |
docs | Write a document somewhere durable — a Google Doc or a Notion page — in the place the user chose. One connector over both, with markdown as the interchange. |
email | Read, search, file, and send email. One connector over Gmail and Outlook; the mailbox is whichever account the task is bound to. |
excel | Read and create .xlsx spreadsheet files. |
faber-mail | Send an email from Faber to the signed-in user's own email address. No setup or OAuth required, but the recipient is always the user themselves. |
files | Keep files where the team keeps them — Google Drive, OneDrive or SharePoint — in the folder the user chose. One connector over both. |
google-business | Read Google Business Profile reviews across every location the account manages, match a reviewer to a contact by name, and reply to reviews. Built for the question "has this client already left us a review?" so the ones who have not can be asked. |
google-docs | Read, create, and edit Google Docs. |
google-drive | Read, upload, and organize files and folders in Google Drive. |
google-sheets | Read and write Google Sheets via the Sheets API. |
http | Fetch any URL or call any API. For human webpages, prefer the `web` connector's `web.extract()` so Faber uses clean extraction instead of raw HTML. Use HTTP for APIs, JSON, RSS, CSV, files, and exact raw responses. |
hubspot | Read and write HubSpot CRM: one parameterized surface over contacts, companies, deals, tickets, notes, tasks, and custom objects. Reads return records you pass straight back into writes. No delete — records are archived to a 90-day recycle bin. |
linear | Teams, projects, workflow states, labels, cycles and comments over Linear's GraphQL API. Read them, comment on an issue, create a project. |
meetings | Reads meeting notes and transcripts from the notetaker the user connected. Granola today; the same code runs against the others as they are added, so a task never names a service. |
notify | Post a message or send a file where the user chose: a channel, an existing chat, a person, their Telegram chat, their email, or the task's run results. The destination is a setting the user fills in. |
notion | Read and change Notion pages and databases — page content, database rows, tables, individual blocks, comments, and saved views — through a flat layer that hides Notion's block and typed-property JSON. |
numbers | Read and create Apple Numbers (.numbers) files. |
pdf | Generate a styled PDF (colors, bold/italic text, font sizes, tables, lists). It is saved as a downloadable file on the run automatically. |
postgres | Read tables and rows, add and update rows, and make additive schema changes in a PostgreSQL database. Supported: `SELECT` reads, `INSERT`/`UPDATE`, and additive DDL (`CREATE TABLE`, `ALTER TABLE ... ADD`). NOT supported: `DELETE`, `DROP`, and `TRUNCATE` — the connector rejects them, so never write a task that deletes rows, columns, or tables. A connection can also be marked read-only, which blocks every write. Works with any real PostgreSQL 12+ database (including Supabase, Amazon RDS, and Neon). When a task runs in the cloud, the database must be reachable from the internet — a database on the user's own machine only works in local runs. |
product-analytics | `productAnalytics` reads bounded aggregate PostHog reports. It never exposes people, event payloads, property values, emails, IP addresses, or replay links. |
profile | A profile is what Faber knows about the person this task acts for: how they write, what they do, what they have answered before. Look something up in it, or record what a run learns. |
search-performance | Read what a search engine's own index says a site earns: which pages and searches bring clicks and impressions, and how that changed. Google Search Console today, and a task never names it. Built for the question an agency has to answer every month, "why is my traffic down", by separating a page that lost its ranking from a page that kept the ranking and lost the click. Read-only: this connector writes nothing. |
sheets | Read and update rows in the spreadsheet the user chose — a Google Sheet or an Excel workbook. One connector over both. |
shopify | Read a Shopify store's commercial pulse: store metadata, bounded order and revenue summaries, low-stock variants, exact inventory item status, and recent successful refunds. Read-only; customer identity and contact fields are unavailable. |
slack | Read a Slack workspace and act in it: history, threads, search, DMs, channel and user lookup, channel administration. |
stripe | Read Stripe payments data: balance, charges, invoices, customers, subscriptions, payouts, and the balance ledger. Read-only. |
telegram | The user's own Telegram chat with the Faber bot, as a place `notify` can post and as a start for a task. The user connects once in Faber settings; the recipient is always the user themselves. |
tracker | File and change tracked work, a Jira issue, a Linear issue, a Trello card, a Notion row, an Asana task, a monday.com item, an Airtable record, or a HubSpot task, in the place the user chose. One connector over all eight. |
trello | The board around the card, over Trello's REST API: boards, lists (columns), checklists, comments and labels. Read them, create a board or a list, move a card, comment on it, label it, assign it. |
web | Search the web and extract clean webpage content through Faber's configured web providers. |
web-analytics | `webAnalytics` reads aggregate website traffic. Cloudflare is the first driver. Every query uses a `WebAnalyticsSite` returned by `listSites`; never construct a site tag, treat it as a zone id, or omit its hostname. Results may be sampled. |
x | Read Twitter/X via API v2. |
xml | Parse untrusted XML with size and complexity limits, DTDs disabled, and no XPath evaluator. |