fix(sdk): auto-heal and normalize protocol version in DirectJsonParser

Open Beginner friendly
#2,599 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
75/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Domain
backend-api-design

Research direction

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.

Written by the indexing model from the issue text.

Description

P2
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
Dominant language
TypeScript
Stars
16.4k
Forks
1.3k
Avg merge
3d 5h
Merged PRs (30d)
117

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from a2ui-project/a2ui

All issues in a2ui-project/a2ui

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.