Plugin system¶

Explicit module loading¶

The default deployment model is an explicit plugin list:

plugins:
  - call_baxter.plugins.system
  - call_baxter.plugins.telegram

Each plugin module exports:

def register(registry, config: dict[str, object] | None = None) -> None:
    ...

The daemon imports each configured module with importlib.import_module(...) and calls register(registry, config) when the function accepts a second argument.

Both simple and configured forms are supported:

plugins:
  - call_baxter.plugins.system
  - module: call_baxter.plugins.telegram
    config:
      database_url: ./tg-state.db
      media_storage_mode: file

Optional entry-point discovery¶

The core loader can also opt into Python entry-point discovery. The default group is call_baxter.plugins, and callers can supply other groups. A discovered entry point must load to a callable and is invoked as register(registry).

This lets independently packaged interfaces advertise plugins without modifying the Call Baxter distribution. For example, cb-social-plugin exposes bluesky, mastodon, and x entry points. Provider-specific configuration still fits the explicit module form because those register() functions also accept (registry, config).

Reload behavior¶

POST /v1/reload and cb reload currently do three things:

1. rebuild the registry
2. re-import configured plugins and call register(...)
3. re-load YAML rules and re-sync schedules

This is a safe start version because it does not attempt hot code reloading of arbitrary Python module changes. For code changes, restarting the daemon remains the clean path. For YAML changes, cb reload is usually enough.

Optional future extensions¶

• file watching for rules.d/*.yml
• separate plugin-owned projection stores for browse-heavy sources like Telegram

Decorator-based plugin DSL (PluginBuilder)¶

New plugins can use PluginBuilder from call_baxter.dsl to reduce boilerplate.

from call_baxter.dsl import PluginBuilder
from call_baxter.registry import Registry

plugin = PluginBuilder("myplugin")

@plugin.event("myplugin.thing", description="A thing happened",
               yields={"ref": "string", "label?": "string"})
def _(): pass

@plugin.poller("myplugin.check", description="Poll for things")
def poll(config: dict) -> list:
    ...

@plugin.action("myplugin.do", description="Do something",
               expects={"target": "string"})
def do_action(plugin_config: dict, action, runtime):
    # plugin_config injected automatically when first param is named 'plugin_config'
    ...

def register(registry: Registry, config=None):
    plugin.register_all(registry, config)

Field shorthand¶

yields and expects accept dicts of "field_name": "type". Keys ending in ? become optional fields; all others are required.

Supported types: string, integer, number, boolean, object, array, datetime.

Action safety contract¶

expects and yields are data-shape contracts. They do not claim that an executor is safe to repeat. Plugin actions should also provide the narrowest accurate ActionExecutionContract through registry.add_action_type(...) or the DSL action declaration. Leave behavior unknown when the runtime cannot prove more.

See Arbitrary actions and replay safety for idempotency boundaries, authorization provenance, replay-eligibility evidence, and recursive on_success / on_error failure semantics.

Available plugins¶

See Sonic Byte plugin for secure command configuration, sound-design options, and complete rule examples.