ai-integrations: catalog processor validation for AiResource agent type

[johnmcollier]

Summary

Extend the AiResource extensions catalog processor in the ai-integrations workspace to validate agent-specific fields when spec.type: agent, rejecting invalid agent entities at ingestion with actionable errors. Add automated processor accept/reject tests; leave non-agent AiResources unchanged.

This issue corresponds to Jira RHIDP-15868. Field set and processor rules are defined in the OpenSpec change below.

Tasks

• Extend AIResourceExtensionsProcessor (or equivalent registered processor path) to validate agent-specific fields when spec.type: agent
• Reject missing/empty/wrong-type spec.instructions with an actionable error naming the field
• Reject clearly wrong optional agent field shapes (e.g. handoffs not an array, resetToolChoice not a boolean) with actionable errors
• Accept opaque string[] for handoffs / tools without entity-ref format enforcement
• Do not add new processor rules for core entity fields such as owner / lifecycle
• Add processor tests for accept and reject paths; ensure spec.type: skill (and other non-agent) entities are unaffected by agent instructions rules
• Keep validation error messages free of internal class names / stack traces

Acceptance Criteria

• Valid agent AiResource entities ingest successfully
• Invalid agent entities are rejected with actionable processor errors (required field missing/empty/wrong type; invalid optional shapes)
• Opaque handoffs / tools string arrays are accepted without ref-format checks
• Non-agent AiResources continue existing extension processor behavior
• Automated tests cover accept and reject paths
• OpenSpec ingestion requirements for this story are satisfied

Specifications

All paths below are relative to workspaces/ai-integrations/.

• openspec/changes/airesource-agent-typed-schema/proposal.md
• openspec/changes/airesource-agent-typed-schema/design.md (especially D3–D5, D10 local processor precedent)
• openspec/changes/airesource-agent-typed-schema/tasks.md (Section 5: Catalog processor validation; Section 7 verification as applicable)
• openspec/changes/airesource-agent-typed-schema/specs/ai-resource-agent-ingestion/spec.md
• openspec/changes/airesource-agent-typed-schema/specs/ai-resource-agent-schema/spec.md (field set / schema-layer context only)

OpenSpec PR (source of truth for this change): #4090

Out of Scope

• Defining the agent field set / catalog-model KindValidator / examples (RHIDP-15867 — ai-integrations: AiResource agent typed schema (catalog-model validator + examples) #4128; depends on that work)
• Upstream RFC + implementation PR (RHIDP-15869)
• Agent runtime, UI, SDK annotation mapping, Component→AiResource migration
• Entity-ref format enforcement for handoffs / tools (explicitly deferred)

Context

• Jira: RHIDP-15868 (processor); epic RHIDP-15865; program ownership RHDHPLAN-1507
• Depends on ai-integrations: AiResource agent typed schema (catalog-model validator + examples) #4128 for the agreed agent field set and preferably merged OpenSpec from PR docs(ai-integrations): OpenSpec for AiResource agent typed schema (RHIDP-15866/15867) #4090
• Prefer extending the existing catalog-backend-module-catalog-backend-module-ai-resource-extensions processor and tests rather than inventing a parallel validation path

[johnmcollier]

Blocked on / depends on schema work in #4128 (RHIDP-15867).

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 5:57 PM UTC · Completed 6:00 PM UTC
Commit: 5093b6b · View workflow run →

[fullsend-ai-triage]

This issue is blocked on #4128 (AiResource agent typed schema), which defines the agent field set, KindValidator, type guard, and example fixtures that the processor validation in this issue needs to build upon.

The OpenSpec PR #4090 has merged, so the design specifications are available. However, the implementation work in #4128 — TypeScript types, catalog-model validator, and examples following the upstream skill/rule discriminated-union pattern — must land first so that the processor validation here has concrete types and field definitions to validate against.

Once #4128 is resolved, this issue should be unblocked and ready for implementation.

Blocked by:

• ai-integrations: AiResource agent typed schema (catalog-model validator + examples) #4128

[johnmcollier]

/fs-code

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 8:38 PM UTC · Completed 8:53 PM UTC

Commit: 258cfc7 · View workflow run →