Azure / Azure/azure-dev

Post-GA: add structured missing-input metadata to the extension protocol

Open
#9,746 0 comments 0 reactions 1 assignee Claimed by @glharper View on GitHub
ai area/error-handling area/ext-framework ext-agents ext-projects
Dominant language
Go
Stars
569
Forks
364
Avg merge
2d 19h
Merged PRs (30d)
136

Description

## Summary

Follow-up to #9571 and #9721. The PR keeps actionable missing-input remediation on the existing
`ActionableErrorDetail.suggestion` and `ExtensionError.suggestion` fields because the extension
protocol is approaching its GA schema freeze.

After GA, add explicit protobuf support so missing-input metadata can round-trip between azd hosts
and extensions without reducing the payload to rendered text.

## Deferred protocol changes

### `errors.proto`

- Add `InputSourceKind` values for flag, environment, and config sources.
- Add `InputSource` with the source name, example value, and complete executable example.
- Add `RequiredInput` with its description and supported sources.
- Add `PromptRequiredErrorDetail` with required inputs, the original prompt message, and the
user-facing error headline.
- Add an optional `prompt_required_error` field to:
- `ActionableErrorDetail` for host-to-extension errors.
- `ExtensionError` for extension-to-host errors.

### `prompt.proto`

- Add an optional `prompt_required_error` field to `ConfirmOptions`, `PromptOptions`, and
`SelectOptions` so extensions can describe remediation before invoking a generic prompt.
- Keep `MultiSelectOptions` unchanged unless its no-prompt behavior is changed to require input.

### Generated and template surfaces

- Regenerate the Go messages in `cli/azd/pkg/azdext`.
- Keep the protocol templates under
`cli/azd/extensions/microsoft.azd.extensions/internal/resources/languages/proto/` aligned with
the core definitions.
- Update generated language SDKs and extension SDK reference documentation.

## Compatibility and rollout

- Make the schema changes additive and preserve all GA field numbers and semantics.
- Retain the rendered `suggestion` fallback so old hosts and extensions remain actionable.
- Add version-skew coverage for old host/new extension and new host/old extension combinations.
- Remove the need for extensions to inspect unknown protobuf fields with `protowire`.

## Acceptance criteria

- `input.PromptRequiredError` metadata round-trips in both host-to-extension and
extension-to-host directions.
- Generic confirm, prompt, and select RPCs preserve supplied missing-input metadata when prompts
are disabled and no default satisfies the request.
- Flag, environment, and config sources retain complete executable examples.
- Core and language-template proto definitions remain synchronized.
- Generated SDKs, extension documentation, and regression tests are updated together.
- Existing suggestion-only peers continue to receive useful remediation.

## Timing

Do not land these protocol changes until the GA schema freeze has been lifted.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.