Plugin development — Shell Sentinel

Overview

Plugins let engineering teams tailor workflows, surface internal guides and expose integrations that feel native in the Shell Sentinel terminal UI. Every Python module placed under the configured plugins/ directory loads at startup, so you can iterate without patching the core distribution.

Lifecycle at a glance

1. Create a module in plugins/ (default) or the directory referenced by SMART_AI_SYS_ADMIN_PLUGINS_DIR.
2. Expose register(registry). The TUI calls it once after the interface boots.
3. Register slash commands, translations, autocomplete hints and logging from that entrypoint.
4. Restart the application to reload the plugin while iterating locally.

Starter command template

The snippet below shows the minimal structure for a conversational command:

# plugins/status_report.py
from smart_ai_sys_admin.plugins import PluginRegistry, PluginSlashCommand


def _server_report(args: list[str]) -> str:
    target = args[0] if args else "default"
    return (
        f"### Status for `{target}`\n"
        "- Pending jobs: 3\n"
        "- Last backup: 2025-10-06\n"
        "- Owner on call: infra@contoso.com"
    )


def register(registry: PluginRegistry) -> None:
    registry.register_translations(
        "en",
        {"plugins": {"status_report": {"description": "Quick status overview"}}},
    )
    registry.register_command(
        PluginSlashCommand(
            name="/status_report",
            aliases=("/statusreport",),
            handler=_server_report,
            description_key="plugins.status_report.description",
        )
    )

Handlers return Markdown that renders in the conversation panel. Any exception is captured by the smart_ai_sys_admin.plugins logger, so keep messages actionable and share remediation tips when failures are recoverable.

Localisation & experience

• Call register_translations(locale, payload) for every supported language; the app resolves them according to the active locale.
• Provide a suggestion callback when you want to customise the inline autocomplete beneath the input field.
• Keep Markdown concise and highlight destructive or irreversible actions so operators can review them before execution.

Testing & observability

• Create fast unit tests or lightweight harness scripts to validate handlers without launching the TUI.
• Toggle verbose logging with SMART_AI_SYS_ADMIN_LOG_LEVEL=DEBUG while iterating locally.
• When a plugin fails to load, inspect logs/app.log and run /status to confirm command registration.

Packaging & distribution

Bundle plugins with deployment artefacts or publish them in an internal package index. Shell Sentinel loads any module available on the plugin path, so document prerequisites such as API keys, environment variables and remote endpoints. Include rollback instructions so operations teams can disable an extension quickly if needed.