Skip to content

Governance Refactoring Plan: OSSA Drupal Implementation (ai_agents_ossa)

This implementation plan executes the engineering actions defined in cgr-001-ossa.yaml, shifting the Drupal module from a monolithic authority into a pure reference implementation bridge for the NPM OpenStandardAgents spec.

User Review Required

[!IMPORTANT]
Removing PhpManifestValidator means the Drupal backend will no longer independently validate YAML strings mathematically against the v0.5.1 schema unless it shells out to Node or delegates validation to a microservice/pipeline before storage. Please confirm the operational boundary for NPM execution (e.g., executing the NPM CLI tool locally vs via an A2A validator service).

Open Questions

  1. NPM Bridging Strategy: When we retire PhpManifestValidator, what is the preferred method for Drupal to invoke @blueflyio/openstandardagents?
  2. Option A: Run validation offline in CI/CD before importing config into Drupal.
  3. Option B: Use exec() or a local node child-process to validate manifests on upload.
  4. Views Integration: We will retire AgentPluginListController and entity.ossa_agent.collection controllers. Should we generate a standard Drupal View configuration (views.view.ossa_agent_catalog.yml) and commit it to the module's config/install directory?

Proposed Changes

CGR Target: Manifest Schema Validation (Upstream)

Replacing PHP-based validation algorithms with the canonical NPM library.

[DELETE] src/Service/PhpManifestValidator.php

  • Remove the custom PHP parser defining the schema math.

[MODIFY] src/Form/OssaAgentImportForm.php (Assumed import handler)

  • Remove calls to PhpManifestValidator.
  • Delegate validation to the external NPM process/service (pending open question).

CGR Target: Catalog UI (Configure)

Retiring custom controllers and replacing with standard Drupal Views.

[DELETE] src/Controller/AgentPluginListController.php

  • Delete the custom PHP class.

[MODIFY] ai_agents_ossa.routing.yml

  • Remove ai_agents_ossa.plugins_overview and entity.ossa_agent.collection routes.

[NEW] config/install/views.view.ossa_agent_catalog.yml

  • Export a standard View that handles sorting, filtering, and displaying the agent catalog natively without custom code.

CGR Target: Registry Storage (Configure)

Ensure storage relies strictly on native Config Entities or Nodes.

[MODIFY] ai_agents_ossa.module & Entity Definitions

  • Verify the ossa_agent node type structure is strictly utilizing Core Fields without proprietary property overrides. (Currently relies on nodes, which satisfies the CGR).

CGR Target: Discovery & Transport (Configure)

Adopt JSON:API for standard discovery endpoints.

[DELETE] src/Controller/OssaDiscoveryController.php

[DELETE] src/Controller/DuadpDiscoveryController.php

[MODIFY] ai_agents_ossa.routing.yml

  • Strip the custom .well-known and /api/ossa/discovery REST routes.
  • Instruct users to leverage Core JSON:API (e.g., /jsonapi/node/ossa_agent) combined with standard URL aliases to achieve the .well-known endpoints without custom controllers.

Verification Plan

Automated Tests

  • Run drush config:import on a fresh instance to ensure the ossa_agent_catalog View correctly replaces the controller UI.
  • Test JSON:API requests to verify the ossa_agent node type exposes data correctly without custom API controllers.

Manual Verification

  • Attempt to import an OSSA manifest and verify it properly fails/succeeds using the new NPM-delegated validation boundary.
  • Navigate to /admin/config/ai/agents and verify the core Views UI renders the registry perfectly.