Agent Abilities (drop-in)

Agent Abilities (drop-in)

An ability is a host-side capability bundle an agent admin grants to an agent
(Codebase Admin, Web Access, Terminal Control, Wiki Control, ...). Abilities are
the latest subsystem to join the core-vs-plugins-structure-philosophy
drop-in model, and the first to live in the new root plugins/ tree.

One file per ability

Each ability is ONE self-describing file in plugins/abilities/. Its
FEATURE dict carries the standard the-feature-header fields plus
ability-specific ones:

• tools — the tool names this ability unlocks (the handlers stay in core).
• group — which UI group it sits in (used to group abilities in both panels).
• icon, color, description, simple — how it renders in the two panels.

Groups are emergent — there is no master group list. The group id an
ability declares decides its bucket: name an existing id (administrator /
basic = "Core" / productivity / web) to join that group, or a new id to
create a new group automatically. A new group gets a default look, or you can
style it from the same file via the optional group_label / group_icon /
group_color / group_desc fields (first ability to style a new group wins).
Known groups render first, emergent ones after. No core or UI edit either way.

Drop a file in → the ability appears everywhere. Delete it → it's gone. To add
one, copy plugins/abilities/_TEMPLATE.py.

One source, five readers

Before this refactor an ability was hardcoded in five places that had to be
kept in sync by hand: the loader's tool map, the connections list in
app/api/agents.py, the feature catalog, and per-ability constants in both
JS panels. Now there is one source — the ability file — and everything reads it:

| Reader | What it takes |
|---|---|
| app/abilities/ (core manager) | scans the files; the single source of truth |
| app/tools/loader.py | the ability -> tools map (for gating) |
| app/features/catalog.py | maturity status (for editions) |
| app/api/agents.py | the per-agent connection rows |
| admin Agent Settings panel + per-agent Abilities tab | render via GET /api/v1/abilities/catalog |

So adding an ability needs no edit to the Python API or either JS panel. The
two panels are sister views (marker SISTER-PANEL: AGENT-ABILITY-TABLE); they now
render from the shared catalog, so only a change to their look must be mirrored.

What stays in core

The tool handlers (e.g. read_source, web_search) still live in core
(app/tools/core_tools.py and friends) — an ability file only declares which
tool names it gates and how it renders. The small group taxonomy (the four
groups) and two credential providers (Web Scraper, Browser Cookies, which are not
abilities) live in the core manager. context_control (a loop-behaviour gate,
not a grantable ability) also stays core.

See app/abilities/__init__.py and docs/claude/production-editions.md.