Allow mixing of catalogs, and use catalogId to resolve name conflicts

[wrenj]

Summary of Changes

This pull request updates the A2UI protocol to support the simultaneous use of multiple catalogs within a single UI surface. By requiring an explicit catalogId on individual components and function calls, the change eliminates potential name collisions and removes the need for surface-level catalog definitions. These modifications improve the scalability of the protocol, allowing for more complex, multi-catalog UI implementations while maintaining strict component resolution.

Highlights

• Catalog Mixing: Enabled the mixing of multiple catalogs within a single surface, allowing for more flexible UI composition.
• Explicit Catalog Resolution: Introduced a mandatory catalogId property for all components and function calls to ensure unambiguous resolution across mixed catalogs.
• API Simplification: Removed the catalogId property from the createSurface message, shifting the responsibility of catalog identification to individual components and function calls.
• Component Constraints: Added a rootOnly boolean property to component definitions to restrict specific components to top-level placement.

[gemini-code-assist]

Code Review

This pull request updates the A2UI protocol to support mixable catalogs, allowing components to specify an optional catalogId to resolve name collisions. It makes catalogId optional in createSurface and removes the requirement for it in subsequent surface-related messages. Documentation in a2ui_protocol.md and evolution_guide.md has been updated to reflect these changes. The reviewer suggested further clarifying the component resolution algorithm and ensuring consistency in the documentation regarding runtime execution boundaries.

[jacobsimionato]

While you were out, I tried to get the less controversial subset of your changes submitted in #2079. I didn't add you as a reviewer because you were out and I know that you wanted to go in this direction. I think what I have is a bit more complete with tests etc, so I'd like to submit that if you're okay with it.

Here is a quick summary of the similarities and differences from Gemini:

What is common

• Both add an optional catalogId property to ComponentCommon and FunctionCall in common_types.json.
• Both make catalogId optional on createSurface, changing the required array from ["surfaceId", "catalogId"] to ["surfaceId"].
• Both update capability schemas to clarify that supportedCatalogIds can be mixed within a single surface.
• Both update a2ui_protocol.md and evolution_guide.md to state that a component's explicit catalogId overrides the surface default catalogId.

How they differ

• PR 2020 directly adds catalogId to FunctionCall, which fails JSON Schema validation under strict unevaluatedProperties: false rules. PR 2079 solves this by introducing FunctionCommon in common_types.json and updating all catalog functions in catalog.json to inherit it via allOf.
• PR 2079 explicitly excludes system functions like @index from inheriting FunctionCommon, preventing them from accepting a catalogId. PR 2020 does not restrict this.
• In updateComponents, updateDataModel, and deleteSurface, PR 2020 deletes the entire sentence requiring createSurface to be sent first. PR 2079 preserves the lifecycle requirement by changing the sentence to require only that createSurface was sent for the surfaceId.
• PR 2020 briefly describes a two-step resolution order for components. PR 2079 defines a three-step resolution order for both components and function calls, adding an explicit callout that there is no fallback to capabilities if neither an explicit nor a surface default catalogId is present.
• PR 2079 requires that all catalogs mixed within a surface conform to the same A2UI specification version. PR 2020 does not mention version rules.
• PR 2020 modifies legacy client and server files (client_capabilities.json, server_to_client.json). PR 2079 modifies updated renderer and agent files (renderer_capabilities.json, agent_to_renderer.json) and replaces lingering clientCapabilities references in a2ui_protocol.md.
• PR 2079 updates schema_helper.py in the Python SDK to traverse allOf subschemas when parsing catalog function arguments. PR 2020 contains no SDK changes.
• PR 2079 adds test cases across four test files to verify optional surface defaults, valid component and function overrides, and rejecting catalogId on @index. PR 2020 includes no tests.