feat(#4128): add AiResource agent typed schema

[fullsend-ai-coder]

Add AgentAiResourceEntityV1alpha1 types, KindValidator, type guard, JSON schema, example fixtures, and unit tests for the agent-shaped AiResource entity (spec.type: 'agent').

Implementation follows the upstream skill/rule discriminated-union pattern from @backstage/catalog-model. Agent entities require spec.instructions (non-empty string) and support optional fields per the design D3 mapping: handoffDescription, model, handoffs, tools, toolUseBehavior, resetToolChoice, modelSettings (temperature, maxTokens, toolChoice), and outputSchema.

Changes:

• plugins/ai-experience-common/src/agent/: new AgentAiResource types,
  validator, type guard, and JSON schema
• examples/ai-resource-agents.yaml: router + specialist multi-agent
  handoff example demonstrating required and optional fields
• examples/ai-resources-oci-skills.yaml: fix plural spec.type
  'skills' -> 'skill' (D8)
• app-config.yaml: wire agent example into catalog locations
• report.api.md: regenerated with new public exports

No @openai/agents-core dependency; opaque string[] for handoffs/tools (no entity-ref format enforcement).

Assisted-by: Claude Opus 4.6

---

Closes #4128

Post-script verification

• Branch is not main/master (agent/4128-airesource-agent-schema)
• Secret scan passed (gitleaks — bb5785cf9f6139b82812b9825cf35738d216944b..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.12%. Comparing base (bb5785c) to head (fec9daf).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4164   +/-   ##
=======================================
  Coverage   58.12%   58.12%           
=======================================
  Files        2422     2423    +1     
  Lines       96490    96502   +12     
  Branches    26844    26849    +5     
=======================================
+ Hits        56080    56092   +12     
+ Misses      40213    40206    -7     
- Partials      197      204    +7     

Flag	Coverage Δ		*Carryforward flag
adoption-insights	84.55% <ø> (ø)		Carriedforward from bb5785c
ai-integrations	70.35% <100.00%> (+0.59%)	⬆️
app-defaults	69.79% <ø> (ø)		Carriedforward from bb5785c
augment	46.67% <ø> (ø)		Carriedforward from bb5785c
boost	76.77% <ø> (ø)		Carriedforward from bb5785c
bulk-import	72.56% <ø> (ø)		Carriedforward from bb5785c
cost-management	13.55% <ø> (ø)		Carriedforward from bb5785c
dcm	60.72% <ø> (ø)		Carriedforward from bb5785c
extensions	56.59% <ø> (ø)		Carriedforward from bb5785c
global-floating-action-button	71.18% <ø> (ø)		Carriedforward from bb5785c
global-header	66.50% <ø> (ø)		Carriedforward from bb5785c
homepage	47.50% <ø> (ø)		Carriedforward from bb5785c
install-dynamic-plugins	59.95% <ø> (ø)		Carriedforward from bb5785c
intelligent-assistant	74.61% <ø> (ø)		Carriedforward from bb5785c
konflux	91.98% <ø> (ø)		Carriedforward from bb5785c
lightspeed	69.02% <ø> (ø)		Carriedforward from bb5785c
mcp-integrations	83.40% <ø> (ø)		Carriedforward from bb5785c
orchestrator	66.87% <ø> (ø)		Carriedforward from bb5785c
quickstart	63.74% <ø> (ø)		Carriedforward from bb5785c
sandbox	79.56% <ø> (ø)		Carriedforward from bb5785c
scorecard	85.98% <ø> (ø)		Carriedforward from bb5785c
theme	88.77% <ø> (ø)		Carriedforward from bb5785c
translations	5.12% <ø> (ø)		Carriedforward from bb5785c
x2a	79.20% <ø> (ø)		Carriedforward from bb5785c

*This pull request uses carry forward flags. Click here to find out more.

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update bb5785c...fec9daf. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rhdh-gh-app]

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@red-hat-developer-hub/backstage-plugin-ai-experience-common	workspaces/ai-integrations/plugins/ai-experience-common	none	v0.4.2

[gabemontero]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:26 PM UTC · Completed 3:41 PM UTC
Commit: fec9daf · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [schema-type-contract-mismatch] workspaces/ai-integrations/plugins/ai-experience-common/src/agent/types.ts:34 — The AgentAiResourceModelSettings TypeScript interface has an index signature [key: string]: JsonValue | undefined that permits arbitrary additional keys, but the corresponding JSON schema sets "additionalProperties": false on modelSettings. The test suite explicitly verifies that unknown properties are rejected (the "rejects modelSettings with unknown property" test), confirming the runtime enforcement of a closed set. The TypeScript type misleadingly tells consumers they can include arbitrary properties that will be rejected at validation time, and this mismatch is visible in the published report.api.md.
  Remediation: Remove the index signature from AgentAiResourceModelSettings so the TypeScript type accurately reflects the closed schema. If JsonObject compatibility is needed at specific call sites, use a utility type or intersection there instead of widening the public interface.

• [stale-reference] workspaces/ai-integrations/examples/ai-resource-oci.yaml:24 — The PR fixes the plural type: skills to singular type: skill in ai-resources-oci-skills.yaml per design decision D8, and the commit message states "fix plural spec.type 'skills' -> 'skill'". However, the same stale plural type: skills remains in examples/ai-resource-oci.yaml at line 24. This file was not included in the fix.
  Remediation: Change spec.type: skills to spec.type: skill on line 24 of workspaces/ai-integrations/examples/ai-resource-oci.yaml.

Low

• [naming-convention] workspaces/ai-integrations/plugins/ai-experience-common/src/agent/AiResource.v1alpha1.agent.schema.json:3 — The JSON schema $id is AiResourceV1alpha1Agent but the TypeScript type is AgentAiResourceEntityV1alpha1. Minor naming asymmetry between the schema identifier and the code-level names (schema puts the discriminant last, TypeScript prefixes it).

• [scope-gap] Issue tasks 6.2 (update docs implying agent typing is blocked on RHDHPLAN-1113) and 6.3 (update package README with agent field table) are listed in the OpenSpec tasks but not addressed in this PR. These documentation tasks may be reasonably deferred to a follow-up.

• [missing-changeset] This PR adds new public types (AgentAiResourceEntityV1alpha1, AgentAiResourceModelSettings) and exports (agentAiResourceEntityV1alpha1Validator, isAgentAiResourceEntity) but includes no changeset file. The CHANGELOG will not reflect this feature addition when the next release is cut.