Skip to content

Interactive App Plugins

Interactive app adapters use a versioned, registry-backed package contract. Bundled and separately installed adapters declare the same descriptor, capabilities, settings model, dependency probe, lifecycle factory, and onboarding metadata.

Operator Configuration

The plugins map is the only supported interactive-app configuration shape. Bundled entries omit distribution. A separately installed plugin must name both its stable plugin id and its normalized Python distribution name:

interactive_apps:
  adapter_host:
    enabled: true
    transport: unix
    host_id: python-adapter-host
    allowed_host_ids: [python-adapter-host]
    token_env_var: ADAPTER_HOST_AUTH_TOKEN
  plugins:
    example.matrix:
      distribution: "acme-ua-matrix"
      execution: adapter_host
      adapter_instance_id: instance-example-matrix
      settings:
        enabled: true
        homeserver: "https://matrix.example.com"

The plugin id and distribution are an exact operator allowlist. The gateway does not import an entry point whose distribution does not match, and it never installs packages at runtime. Installation is a separate operator action.

Inspect the effective catalog and package diagnostics with:

.venv/bin/python assistant_cli.py interactive-app-list \
  --config <instance_root>/instance_config.yaml \
  --env <instance_root>/team.env

run-app --app accepts either the registered plugin id or its declared channel name. The bundled headless launcher starts the adapter host automatically when it is enabled and at least one enabled channel selects execution: adapter_host. For manual operation, start the gateway first and then run:

.venv/bin/python assistant_cli.py run-adapter-host \
  --config <instance_root>/instance_config.yaml \
  --env <instance_root>/team.env

Set ADAPTER_HOST_AUTH_TOKEN (or its _FILE form) to a random value of at least 32 characters. transport: unix also verifies the peer process user and applies the configured socket permissions. Use transport: mtls across containers or hosts; configure separate listener and connection addresses, server/client certificates, private keys, trust bundles, and a server name. The client certificate DNS/URI identity or common name must exactly match the claimed host_id.

Package Entry Point

Packages register one zero-argument descriptor provider in the versioned universal_agents.chat_adapters.v1 entry-point group. The entry-point name must equal the descriptor's plugin_id:

[project.entry-points."universal_agents.chat_adapters.v1"]
"example.matrix" = "acme_ua_matrix:interactive_app_descriptor"

Import the package-facing API only from assistant_gateway.interactive_apps.plugin_api. A descriptor provides:

  • a stable plugin id, channel name, API version, and implementation version;
  • an explicit Pydantic settings model containing enabled: bool;
  • declared capabilities;
  • a local dependency probe that performs no external lifecycle work;
  • a factory that receives only the validated plugin settings, gateway adapter-application protocol, normalized inbound bridge, and explicit bounded host ports;
  • onboarding summary, setup order, secret-reference names, and documentation.

The host derives distribution name, version, and entry-point provenance from installed package metadata. A plugin cannot self-assert or override that provenance.

Boundary Rules

Package plugins do not receive aggregate gateway configuration, repositories, database handles, message-broker clients, authorization implementations, or credential values. They translate platform events into normalized application requests and translate application delivery events back to the platform. Because canonical gateway identity is also unavailable outside this boundary, an externally hosted adapter applies its configured platform user/chat allowlists exactly; it cannot treat a linked gateway user as an implicit edge allowlist entry.

One plugin's discovery, dependency, construction, or startup failure is reported independently. Unrelated enabled adapters continue by default; an explicit run-app selection remains strict so operator tests fail immediately.

The in-process API is intended for trusted, explicitly installed packages. It is not a sandbox or an authorization boundary. External hosting adds process and transport isolation, not arbitrary-code sandboxing; packages remain an operator installation and allowlist decision.

Delivery and Recovery Semantics

One adapter-host process may run several configured plugins. Registration and health remain independent per plugin. Each registration negotiates capabilities, payload and attachment sizes, queue credit, heartbeat timing, acknowledgement deadlines, and retention.

Inbound requests are durably admitted before the gateway returns acceptance. Outbound delivery has separate durable received and platform-completion acknowledgements. Reconnect creates a new epoch and resumes from committed cursors; stale epochs and sequence gaps fail closed. The transport is at-least-once. A platform call with an ambiguous result is recorded as outcome_unknown and is not blindly repeated.

The gateway keeps a bounded persistent outbox per adapter. At capacity it returns observable backpressure instead of dropping an event. Health reports lease liveness, readiness, queue depth, in-flight work, oldest pending age, cursor progress, reconnect count, and redacted adapter errors. Terminal records are pruned only after the configured retention window; a client older than that floor receives an explicit resynchronization error.

The internal Website/Web Chat plugin must use execution: in_process. It is an operator surface owned by the gateway rather than a channel-only adapter.