extension-boundaries

name	extension-boundaries
description	Use when touching Pawrrtal channels, providers, tools, plugins, subagents, context providers, turn orchestration, or code that decides where an integration should live. Enforces the split between generic kernel code, manifest plugins, trusted runtime adapters, provider adapters, channel adapters, and agent runtime primitives.

Pawrrtal Extension Boundaries

Use this before changing backend extension code. The goal is a thin generic kernel with optional pieces installed as plugins.

Channel Adapters

A channel adapter talks to one user surface, such as Telegram or Google Chat. Channel-specific code belongs under backend/app/channels/<channel>/ or behind a channel plugin capability.

Channel adapters should:

• Normalize inbound/outbound messages through the channel base types.
• Choose a model and call the generic turn runner.
• Keep provider internals, SDK payloads, and tool factories out of channel code.
• Move reusable formatting to channel runtime helpers or a channel adapter.

If a new surface can send a message and receive a response, treat it as a channel unless it is purely a local CLI/operator concern.

Kernel Rules

The kernel owns auth, workspaces, persistence, turn orchestration, plugin discovery, enabled state, env resolution, and stable interfaces.

Directory rules:

• Keep backend/app/chat/ provider-agnostic and channel-agnostic.
• Keep turn orchestration generic in backend/app/turns/pipeline/; do not add provider, channel, or tool special cases to the pipeline.
• Tool selection happens in the tool-surface/plugin layer, not inside providers or route handlers.
• Share optional behavior through kernel interfaces, slots, or runtime adapters instead of direct plugin-to-plugin imports.

Smells to fix:

Smell	Fix
chat/ imports a provider, MCP adapter, or channel module	Move the behavior behind a generic interface or plugin capability.
Turn orchestration checks for one provider, tool, or channel by name	Emit/handle a generic event or add an adapter hook.
A subagent is implemented as a plugin	Move orchestration to the agent runtime and let plugins contribute profiles or invoke it.

Conversation Boundaries

backend/app/conversations/ owns provider-agnostic conversation data and workflows. It must not grow provider-specific history helpers, thread stores, or channel formatting code.

Smells to fix:

Smell	Fix
conversations/ contains gemini_*, codex_*, or another provider name	Move it to the provider package and expose a generic history adapter.
Conversation code formats Telegram or Google Chat output	Move it to the channel adapter.

Plugin Platform

A plugin manifest is backend/plugins/<plugin_id>/plugin.json. It is declarative metadata: capabilities, env requirements, validation commands, permissions, slots, and entrypoints.

Plugin runtime code lives in backend/app/plugins/. It is trusted host code plus bundled Python implementations that a manifest may activate.

A slot is a named extension point where multiple plugins can fit, such as tasks, web_search, channel:telegram, provider:models, or conversation_memory.

Before adding optional behavior:

1. Name the capability type: provider, channel, cli_tool, python_tool, turn_context_provider, conversation_memory, agent_runtime, agent_profile, router, settings, or scheduler.
2. Name the slot if users may choose among multiple implementations.
3. Decide whether the code is generic kernel code or a trusted bundled adapter.
4. Add or update the manifest first when the behavior is optional.
5. Declare env requirements in the manifest. Use user_workspace or workspace scope when values must be overridable per workspace/user.
6. Keep enabled/disabled behavior explicit. Disabled plugins must not advertise tools, providers, channels, or context providers.
7. Add tests at the interface: manifest validation, registry/slot resolution, enabled-state behavior, env gating, and the runtime adapter.
8. Verify through Paw when the behavior affects a user-visible flow.

Plugin smells to fix:

Smell	Fix
Plugin code reads os.environ directly for user/workspace settings	Declare env in the manifest and use the plugin env resolver.
A plugin is always on because it exists on disk	Add enabled-state tests and make the manifest default intentional.
Plugins import each other directly	Share behavior through kernel interfaces, slots, or runtime adapters.

Provider Adapters

A provider adapter talks to one model provider or provider CLI. It belongs under backend/app/providers/ or behind a provider plugin capability.

Provider adapters should:

• Translate generic AgentTool objects into SDK-specific formats.
• Avoid importing tool modules or tool factories directly.
• Keep channel-specific formatting and command output out of providers.
• Keep provider-specific history/session code inside the provider package and expose generic adapters to the rest of the app.

Smells to fix:

Smell	Fix
A provider imports tool factories	Pass generic AgentTool values into the provider and translate there.
A channel imports provider internals	Route through the generic turn runner or provider factory.

Verification

Use Paw as the operator surface for the supported CLI slice. From the repo root, prefer just paw.

just paw doctor --json
just paw context --json

For runtime changes, add focused tests and then run the relevant gates:

cd backend && uv run pytest tests/test_plugin_discovery.py tests/test_plugin_tools.py
cd backend && uv run pytest tests/test_channel_plugins.py tests/test_provider_plugins.py

Run broader CI gates before claiming the PR is ready.