Charliehub · by A.N.D.Why

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

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.

gmail / manifest.json (trimmed)
{
  "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

FieldWhat it does
roleThe job this extension takes on. One of "email", "remotePersistence" or "rdbmsPg".
roleScopedSet 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.
persistenceRequired with "remotePersistence". Points to the module that does the storing. See Data & storage.
rdbmsRequired 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.

RoleRequired tools
emailemail__search, email__read, email__draft, email__list_labels, email__create_label, email__apply_labels
remotePersistenceremote_storage__document__create, __read, __update, __delete and __list. The remote_storage__data__* tools are optional.
rdbmsPgrdbms_pg__query and rdbms_pg__describe. rdbms_pg__import and rdbms_pg__export are optional.

Things to know

See it in

Every field in detail: role in the reference.