agentic-mobile-control/openspec/specs/plugin-system/spec.md

plugin-system Specification

Purpose

TBD - created by archiving change cloud-runtime. Update Purpose after archive.

Requirements

Requirement: Plugin manifest schema

The system SHALL define a PluginManifest schema with a unique name, a version, an entry_point_kind restricted to driver, tool, or skill, and a target (a dotted module:attribute reference to the plugin's implementation), and SHALL reject a manifest missing any required field or using an unrecognized entry_point_kind.

Scenario: Valid manifest accepted

• WHEN a manifest with all required fields and a recognized entry_point_kind is submitted for registration
• THEN the registry accepts it and stores it as a known plugin

Scenario: Manifest with unrecognized entry_point_kind rejected

• WHEN a manifest declares an entry_point_kind other than driver, tool, or skill
• THEN the registry rejects it with a clear validation error and does not register it

Scenario: Duplicate plugin name rejected

• WHEN a manifest is submitted whose name matches an already-registered plugin
• THEN the registry rejects the new registration with a clear conflict error rather than silently overwriting the existing entry

Requirement: Plugin discovery via entry points and manifest files

The system SHALL discover plugin manifests both from installed Python packages declaring an entry point in the device_agent_runtime.plugins group and from local plugin.json files under a configured scan path, feeding both sources into the same validation-and-registration path.

Scenario: Discovery via installed entry point

• WHEN an installed package declares an entry point in the device_agent_runtime.plugins group resolving to a valid manifest
• THEN PluginRegistry.discover() finds and registers it

Scenario: Discovery via local manifest file

• WHEN a plugin.json file exists under the configured plugin scan path and parses into a valid manifest
• THEN PluginRegistry.discover() finds and registers it

Scenario: Malformed manifest file is skipped, not fatal

• WHEN a plugin.json file under the scan path fails to parse or fails schema validation
• THEN PluginRegistry.discover() skips that file, records it as a discovery error, and continues discovering remaining plugins rather than aborting the whole scan

Requirement: Driver-kind plugins register into the driver registry extension point

The system SHALL, for a manifest with entry_point_kind == "driver", resolve its target to a driver-factory builder and register it under the manifest's name as a new driver_type in the existing driver-registry extension point, without requiring any edit to the driver package's own files.

Scenario: Driver plugin registered successfully

• WHEN a valid driver-kind manifest is registered and its target resolves to a callable driver-factory builder
• THEN the manifest's name becomes usable as a driver_type value by any caller building a driver factory, with no change to existing driver-registry code

Scenario: Driver registry extension point unavailable

• WHEN a driver-kind manifest is registered but the driver-registry's registration function is not importable in the running environment
• THEN the registry raises a clear, explicit error naming the missing integration point, rather than silently accepting the manifest without wiring it

Requirement: Tool and skill plugin manifests are accepted but explicitly marked unwired

The system SHALL accept and store tool- and skill-kind plugin manifests (listable like any other registered plugin) but SHALL report them as not wired to any execution path, rather than implying they are active.

Scenario: Tool-kind manifest registered

• WHEN a valid tool-kind manifest is registered
• THEN the registry stores it and it appears in a plugin listing with a wired: false indicator, and no tool dispatch path is modified as a result

Scenario: Skill-kind manifest registered

• WHEN a valid skill-kind manifest is registered
• THEN the registry stores it and it appears in a plugin listing with a wired: false indicator, and no skill store or execution path is modified as a result