[DO NOT MERGE YET] feat(ui): unify settings with form extension

[PetrBulanek]

Summary

Unifies settings with the Form extension by adding settings_form, updating the UI to render settings from form demands with legacy fallback, and tightening fulfillment routing so only the demanded extension is fulfilled. Adds checkbox group support in form schemas/UI, new validation for required groups, and docs updates with deprecation and migration guidance for legacy settings.

Notice: Python SDK parity is still pending. We still need to implement settings_form support and legacy settings deprecation/migration behavior in the Python SDK. @jezekra1

Linked Issues

Closes: #1863

Documentation

• No Docs Needed:

If this PR adds new feature or changes existing. Make sure documentation is adjusted accordingly. If the docs is not needed, please explain why.

[gemini-code-assist]

Summary of Changes

Hello @PetrBulanek, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant architectural enhancement by integrating agent settings directly into the existing Form extension. The primary goal is to streamline the configuration process by deprecating the standalone ui/settings extension in favor of a new settings_form within the more versatile Form extension. This change not only modernizes the settings mechanism but also expands form capabilities with the addition of checkbox_group fields and robust validation. The UI has been updated to gracefully handle both the new settings_form and legacy settings, ensuring a smooth transition. Furthermore, the PR tightens fulfillment routing, ensuring that only explicitly requested extensions are processed, and provides clear documentation for migration.

Highlights

• Settings Unification: The ui/settings extension is now unified with the services/form extension, introducing a settings_form type for managing agent settings.
• Checkbox Group Support: A new checkbox_group field type has been added to form schemas and UI, allowing for structured groups of checkboxes.
• Enhanced Validation: New validation logic is implemented for required checkbox groups, ensuring at least one option is selected.
• Legacy Fallback & Deprecation: The UI is updated to render settings from the new form demands, with a fallback mechanism for legacy settings, and the old ui/settings extension is marked for deprecation.
• Fulfillment Routing Tightening: The fulfillment routing logic has been refined to ensure only the explicitly demanded extension is fulfilled, improving clarity and preventing unintended fulfillments.
• Documentation & Migration Guide: Comprehensive documentation updates include deprecation notices and a detailed migration guide for transitioning from legacy settings to the new settings_form approach.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• apps/agentstack-sdk-ts/src/client/a2a/extensions/common/form/schemas.ts
  • Introduced checkboxGroupFieldSchema and checkboxGroupFieldValueSchema for defining checkbox group structures and their values.
  • Integrated these new schemas into the formFieldSchema and formFieldValueSchema discriminated unions.
• apps/agentstack-sdk-ts/src/client/a2a/extensions/common/form/types.ts
  • Added type definitions for CheckboxGroupField and CheckboxGroupFieldValue.
• apps/agentstack-sdk-ts/src/client/a2a/extensions/services/form/schemas.ts
  • Defined new schemas (settingsFormFieldSchema, settingsFormFieldValueSchema, settingsFormRenderSchema, settingsFormValuesSchema, settingsFormResponseSchema) to represent settings within the form extension.
  • Extended formDemandsSchema and formFulfillmentsSchema to include settings_form.
• apps/agentstack-sdk-ts/src/client/a2a/extensions/services/form/types.ts
  • Exported new types related to the settings form (SettingsFormField, SettingsFormFieldValue, SettingsFormRender, SettingsFormValues, SettingsFormResponse).
• apps/agentstack-sdk-ts/src/client/a2a/extensions/ui/settings/index.ts
  • Marked the settingsExtension as deprecated.
• apps/agentstack-sdk-ts/src/client/core/extensions/types.ts
  • Marked the settings fulfillment function as deprecated.
• apps/agentstack-ui/src/modules/form/components/FormField.tsx
  • Added rendering support for the new checkbox_group field type.
• apps/agentstack-ui/src/modules/form/components/fields/CheckboxGroupField.module.scss
  • Added new styling for the CheckboxGroupField component.
• apps/agentstack-ui/src/modules/form/components/fields/CheckboxGroupField.tsx
  • Implemented the CheckboxGroupField component, including validation for required groups.
• apps/agentstack-ui/src/modules/form/components/fields/CheckboxGroupFieldItem.tsx
  • Created CheckboxGroupFieldItem for individual checkboxes within a group.
• apps/agentstack-ui/src/modules/form/constants.ts
  • Introduced REQUIRED_GROUP_ERROR_MESSAGE for checkbox group validation.
• apps/agentstack-ui/src/modules/form/hooks/useFormFieldValidation.ts
  • Enhanced the validation hook to support custom rules and named fields, improving flexibility for complex form structures.
• apps/agentstack-ui/src/modules/form/utils.ts
  • Updated getDefaultValues to correctly initialize checkbox_group fields.
• apps/agentstack-ui/src/modules/messages/components/MessageFormResponse.tsx
  • Added logic to display values for checkbox_group fields in message responses.
• apps/agentstack-ui/src/modules/runs/contexts/agent-demands/AgentDemandsProvider.tsx
  • Refactored settings state management to align with the new settings_form structure, including initial value handling and dynamic fulfillment.
  • Modified provideFormValues to accept a formId parameter, enabling distinct handling for different form types.
• apps/agentstack-ui/src/modules/runs/contexts/agent-demands/agent-demands-context.ts
  • Updated context types to reflect the new settings_form and provideFormValues signature.
• apps/agentstack-ui/src/modules/runs/contexts/agent-demands/build-fulfillments.ts
  • Adjusted fulfillment logic to prioritize settings_form and provide backward compatibility for legacy settings.
  • Added a utility to transform new settings form values back to legacy format.
• apps/agentstack-ui/src/modules/runs/contexts/agent-run/AgentRunProvider.tsx
  • Updated provideFormValues calls to explicitly specify formId: 'initial_form'.
• apps/agentstack-ui/src/modules/runs/settings/RunSettings.tsx
  • Adapted to use the new settingsForm from useAgentDemands.
• apps/agentstack-ui/src/modules/runs/settings/RunSettingsForm.tsx
  • Updated to render settings based on the SettingsFormRender structure, utilizing new field components.
• apps/agentstack-ui/src/modules/runs/settings/SingleSelectSettingsField.tsx
  • Refactored to work with the new SingleSelectField type and getFieldName utility.
• apps/agentstack-ui/src/modules/runs/settings/ToggleSettingsField.tsx
  • Refactored to work with CheckboxField and CheckboxGroupField types and getFieldName utility.
• apps/agentstack-ui/src/modules/runs/settings/utils.ts
  • Introduced getInitialSettingsFormValues, transformLegacySettingsDemandsToSettingsForm, and transformSettingsFormValuesToLegacySettingsValues for managing settings data conversion and initialization.
• apps/agentstack-ui/src/utils/helpers.ts
  • Removed the objectFromEntries helper function.
• docs/development/custom-ui/agent-requirements.mdx
  • Updated documentation to deprecate the old settings and introduce the new settings_form with migration instructions and code examples.

Activity

• PetrBulanek initiated this pull request to unify settings with the form extension.
• The changes involve significant updates across SDK schemas, UI components, and context providers to support the new settings model.
• New UI components for CheckboxGroupField and CheckboxGroupFieldItem were added.
• Documentation was updated to reflect the deprecation of the old settings and provide a migration guide for the new settings_form.
• The PR description notes that Python SDK parity for settings_form support and legacy settings deprecation/migration is still pending, indicating a future task.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a significant feature enhancement that unifies the agent settings mechanism with the Form extension. It introduces a new settings_form demand, deprecates the old settings extension, and provides a backward-compatibility layer for a smooth transition. The changes are comprehensive, touching the SDK schemas and types, the UI provider for agent demands, and the settings components themselves. A new checkbox_group form field type has been added, complete with UI components and validation. The documentation has also been updated with deprecation notices and a migration guide.

My review finds the implementation to be robust and well-thought-out. The backward compatibility logic is sound, and the refactoring of UI components to use the new form-based settings structure is clean. I have one suggestion to improve the user experience when displaying submitted checkbox group values.

[tomkis]

@jjeliga will look into Python code.