a2ui-project / a2ui-project/a2ui
fix(sdk): auto-heal and normalize protocol version in DirectJsonParser
- Lenguaje dominante
- TypeScript
- Estrellas
- 16.4k
- Forks
- 1.3k
- Merge medio
- 3 d 15 h
- PR fusionados (30 d)
- 134
Descripción
### Description
In the Direct JSON inference format (`DirectJsonFormat`), the LLM directly emits raw A2UI JSON message streams. The A2UI protocol schemas strictly require a top-level `"version"` property with a leading `'v'` (e.g., `"v0.9"`, `"v0.9.1"`, `"v1.0"`).
Because standard software version conventions use numeric strings (e.g. `"0.9"`, `"1.0"`), and system prompt workflow rules do not heavily emphasize envelope version string trivia, LLMs frequently omit the leading `'v'` (emitting `"version": "0.9"`) or omit the `"version"` property altogether. This causes non-deterministic schema validation failures (e.g., recent CI evals failure in #2594 where 5 samples failed solely due to `'0.9' is not one of ['v0.9', 'v0.9.1']`).
In contrast, other inference format compilers (`ExpressCompiler`, `ElementalCompiler`, `AtomCompiler`) deterministically inject the canonical target protocol version into compiled message payloads rather than burdening the LLM with envelope version formatting.
### Proposed Solution
1. **Auto-heal / Normalize Version in `DirectJsonParser`**:
- In `DirectJsonParser.compile()` (and `parse_and_fix`), check each compiled A2UI message dictionary.
- If `"version"` is missing the leading `'v'` (e.g. `"0.9"`, `"0.9.1"`, `"1.0"`), normalize it to `"v0.9"`, `"v0.9.1"`, or `"v1.0"`.
- If `"version"` is omitted entirely, deterministically inject the target protocol version associated with the catalog/format (e.g. `f"v{catalog.version}"`).
2. **Harmonize Evaluation & Specialist Parsing**:
- Ensure `subagent_tool` and evaluation scorers rely on `DirectJsonParser.compile()` so that syntax healing (smart quotes, trailing commas, and version normalization) is consistently applied.
### Related
- Relates to #2594
Guía de contribución
Línea de trabajo
The issue is in the DirectJsonParser's compile and parse_and_fix methods. Look for the DirectJsonParser class in the codebase, likely in a file like `src/sdk/parser/direct_json_parser.ts`. Examine how it processes A2UI message dictionaries. The fix involves checking the 'version' property, adding a leading 'v' if missing, or injecting the catalog version. Run existing tests for the parser to ensure the normalization works.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Área
- backend-api-design
- Tipo de issue
- Error
- Dificultad
- 2/5
- Tiempo estimado
- 1-3 horas
- Estado de actividad
- Activo
- Claridad
- Bien especificado
- Aptitud para principiantes
- 75/100