Building block 6 · Going further
Roles
A role is a job that only one extension can do at a time, like "the email account" or "where the person's documents are stored". Fill a role, and people can swap your extension for another provider without anything else in Charlie changing.
What you'd use it for
- Connect an email account so Charlie and other extensions can search, read and draft mail.
- Give Charlie somewhere to keep documents and records that isn't this one computer.
- Provide a PostgreSQL database that other extensions can keep their tables in.
- Let someone switch providers later without retraining Charlie or rewriting the extensions that rely on you.
In your manifest
This is from the gmail extension, which holds the email role. Each tool is marked "roleScoped", so Charlie shows it to the model by its plain name.
{
"name": "gmail",
"role": "email",
"connections": [
{ "name": "gmail", "authType": "oauth2-static",
"transport": "rest-client" }
],
"tools": [
{
"name": "email__search",
"description": "Search the connected account...",
"handler": "./handlers/search.js",
"roleScoped": true
},
{
"name": "email__draft",
"description": "Create a draft. This NEVER sends...",
"handler": "./handlers/draft.js",
"roleScoped": true
}
]
}What each part means
| Field | What it does |
|---|---|
role | The job this extension takes on. One of "email", "remotePersistence" or "rdbmsPg". |
roleScoped | Set on a tool. The model sees the tool's bare name, such as email__search, with no sign of which extension provides it. Only allowed when the manifest has a role. |
persistence | Required with "remotePersistence". Points to the module that does the storing. See Data & storage. |
rdbms | Required with "rdbmsPg". Points to the module that runs the database calls. |
Tools each role must provide
Charlie checks these names among your roleScoped tools. If one is missing, your extension is skipped.
| Role | Required tools |
|---|---|
email | email__search, email__read, email__draft, email__list_labels, email__create_label, email__apply_labels |
remotePersistence | remote_storage__document__create, __read, __update, __delete and __list. The remote_storage__data__* tools are optional. |
rdbmsPg | rdbms_pg__query and rdbms_pg__describe. rdbms_pg__import and rdbms_pg__export are optional. |
Things to know
- One holder at a time. Charlie refuses to switch on a second extension with the same role. Switch off the current one first.
- Plain names on purpose. Because only one extension can hold a role, a
roleScopedtool name can't clash. That is also why swapping providers changes nothing the model sees. - Email never sends. Other extensions reach the email account through
ctx.email, which allows only these operations:list_labels,create_label,modify_message_labels,modify_thread_labels,search_messages,get_message,get_threadandcreate_draft. There is deliberately no send. - Email needs Charlie's help. Charlie itself talks to the mail service, so the sign-in token never reaches extension code. Today it knows how to do that for
gmailonly. Another extension claiming"email"leavesctx.emailempty. - Depending on a role. An extension that needs whoever holds a role, rather than one named extension, can list it in
"requiresRole". With no holder switched on, that extension is skipped. - Publishing checks too. The catalog runs the same required-tool check when you publish, and rejects a bundle that fails it.
See it in
Every field in detail: role in the reference.