Core vs Plugins: Structure Philosophy

Core vs Plugins: Structure Philosophy

webAgent separates a small core from many external plugins. The rule:

A new capability is a new file in a plugin folder — never an edit to the core.

The app discovers plugin files at runtime, so you register nothing by hand.
This is what makes editions-and-the-production-path possible: a production
build can include only the plugin files it trusts.

Where each capability type lives

| Capability | Folder | Add by |
|---|---|---|
| OAuth / API integration | app/integrations/ | a file exposing a TOOLS list |
| Event source ("when X happens") | app/events/sources/ | a file exposing source_cls |
| Communication channel | app/communications/plugins/ | a file exposing plugin_cls |
| Data connector | app/connectors/ | a Connector subclass (type_name) |
| Secrets vault | app/secrets/ | a SecretsBackend subclass (.name) |
| Encryption method | app/encryption/ | an EncryptionBackend subclass |
| Payment processor | app/billing/processors/ | a file exposing processor_cls |
| Scheduler provider | app/scheduler/providers/ | a file exposing a PROVIDER dict |
| Agent ability | plugins/abilities/ | a FEATURE file (tools it gates + UI metadata) — see agent-abilities-drop-in |

The root plugins/ tree. The canonical home for drop-in capability files is a
top-level plugins/ folder (sibling to app/), so "plugin vs core" is
structural, not just convention. Abilities live there now. The app/…
subsystems above are migrating into plugins/ one at a time — until each moves,
add its plugins in the app/… folder shown. In every case the **core
manager/base class stays in app/**; only the swappable leaf files live under
plugins/.

Every plugin also carries a the-feature-header so editions know its maturity.

Do NOT

• Wire a new capability into the core: app/tools/loader.py,

app/tools/core_tools.py, or app/main.py.

• Add it to a central if/elif or registry list — discovery handles that.

Do

• Copy app/integrations/_TEMPLATE.py as a starting skeleton.
• Add a FEATURE header with an honest status.
• Delete the file to remove the capability — nothing else references it.

What stays in the core (never editioned out)

The agent-loop essentials (tool/skill discovery tools, time/date/calculator/
read-attachment, the DB-query tool, memory), the SQLite storage fallback, the
inline-DB secrets bootstrap, and no-encryption pass-through. Everything
else — including web search (via the web_access ability) — is a demotable add-on.

Next: adding-a-plugin.