fix: a2ui agent catalog handoff

[PupilTong]

Summary

• Add an agent-facing A2UI playground catalog built from the renderer's built-in component manifests and basic function definitions.
• Send that catalog with initial chat and live action stream requests so the server prompt and validator match what the preview can render.
• Key cached A2UI agents by effective catalog contents and raise the default A2UI request body limit for catalog-carrying requests.
• Record follow-up project instructions for keeping playground/server catalog handling aligned.

Root Cause

The playground preview rendered with its own built-in catalog, but requests to the A2UI server omitted catalog data. The server therefore fell back to BASIC_CATALOG, which could miss components such as PieChart and function definitions, causing the agent prompt and validation rules to drift from the renderer.

Validation

• CI=1 pnpm dprint fmt .github/a2ui-catalog.instructions.md .github/a2ui-server.instructions.md packages/genui/a2ui-playground/src/catalog/a2uiAgentCatalog.ts packages/genui/a2ui-playground/src/pages/AIChatPage.tsx packages/genui/server/app/a2ui/_shared.ts packages/genui/server/service/a2ui-agent.ts
• CI=1 pnpm exec tsc -p tsconfig.json --noEmit in packages/genui/server
• CI=1 pnpm turbo build --filter a2ui-playground

Summary by CodeRabbit

• New Features

  • A2UI agent requests now include complete catalog information for improved synchronization.

• Documentation

  • Updated A2UI catalog and server agent instructions.

• Improvements

  • Increased default request body size limit from 64KB to 256KB.
  • Enhanced catalog caching mechanism for better performance.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 62427e4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6d2eeff0-70f5-4cff-9d98-dc11aecac91d

📥 Commits

Reviewing files that changed from the base of the PR and between 3794d0c and 62427e4.

📒 Files selected for processing (6)

• .github/a2ui-catalog.instructions.md
• .github/a2ui-server.instructions.md
• packages/genui/a2ui-playground/src/catalog/a2uiAgentCatalog.ts
• packages/genui/a2ui-playground/src/pages/AIChatPage.tsx
• packages/genui/server/app/a2ui/_shared.ts
• packages/genui/server/service/a2ui-agent.ts

---

📝 Walkthrough

Walkthrough

This PR establishes a playground-specific A2UI catalog, wires it through playground agent requests, and updates server-side caching to use the full catalog content rather than just the catalog id to ensure consistent agent behavior across catalog updates.

Changes

A2UI Catalog Propagation and Server Caching

Layer / File(s)	Summary
Catalog data shapes and assembly packages/genui/a2ui-playground/src/catalog/a2uiAgentCatalog.ts	Introduces A2UIAgentCatalogProp, A2UIAgentCatalogComponent, A2UIAgentFunctionSpec, and A2UIAgentCatalog interfaces; implements inferType, inferEnums, componentFromManifest, and basicFunctionDefinitions helpers; assembles and exports A2UI_AGENT_CATALOG from catalog manifests and basic functions.
Playground catalog propagation to agent packages/genui/a2ui-playground/src/pages/AIChatPage.tsx	Imports A2UI_AGENT_CATALOG and includes it in both the initial chat generation request and action-stream request payloads to the A2UI agent service.
Server-side catalog-aware caching packages/genui/server/service/a2ui-agent.ts	Adds hashCatalog() helper to compute SHA-256 hash of catalog content; updates getAgent to include the catalog content hash in cache keys and resolve opts.catalog to BASIC_CATALOG when undefined; passes the resolved catalog to agent creation.
Request body size limit packages/genui/server/app/a2ui/_shared.ts	Increases default MAX_BODY_BYTES from 64 KB to 256 KB to support larger catalog payloads.
Development guidance and instructions .github/a2ui-catalog.instructions.md, .github/a2ui-server.instructions.md	Documents catalog synchronization requirements between renderer, agent catalog, and Lynx builtins; describes server agent prompt construction and catalog propagation across system prompt, render, cache, and validation layers.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• lynx-family/lynx-stack#2718: Both PRs coordinate A2UI catalog/built-ins wiring; this PR adds the playground agent catalog contract, while the related PR extends the server agent catalog with new components like DateTimeInput—they share the catalog synchronization flow and must remain aligned.

Suggested reviewers

• HuJean
• gaoachao
• Sherry-hue

Poem

🐰 A catalog springs to life with care,
Each prop and function nestled there,
From playground to the server's keep,
Hashed and cached so promises run deep. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: a2ui agent catalog handoff' directly and accurately describes the main change: fixing catalog synchronization between the A2UI playground renderer and the agent service to ensure they use the same catalog.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch hw/codex/a2ui-agent-catalog-chain

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 81 untouched benchmarks
⏩ 26 skipped benchmarks¹

---

_{Comparing hw/codex/a2ui-agent-catalog-chain (62427e4) with main (3794d0c)}

Footnotes

1. 26 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[github-actions]

UI Judge

GEQI weighted score: 60.9 / 100 across 8 examples.
Average visual-correctness score: 3.3 / 5.

Dimension	Weight	Average	Results	Status
Usability & Interaction	30%	2.8 / 5	8	OK
Visual & Aesthetics	25%	3.3 / 5	8	OK
Consistency & Standards	15%	3.3 / 5	8	OK
Architecture & UX Writing	15%	3.1 / 5	8	OK
Accessibility & Performance	15%	3 / 5	8	OK

#	Example	Visual Correctness	Usability & Interaction (30%)	Visual & Aesthetics (25%)	Consistency & Standards (15%)	Architecture & UX Writing (15%)	Accessibility & Performance (15%)	GEQI	Page	Status
1	recs	2 / 5	2 / 5	3 / 5	2 / 5	2 / 5	2 / 5	45 / 100	preview	OK
2	cast-grid	5 / 5	3 / 5	4 / 5	5 / 5	5 / 5	4 / 5	80 / 100	preview	OK
3	citywalk-list	2 / 5	3 / 5	3 / 5	2 / 5	2 / 5	3 / 5	54 / 100	preview	OK
4	fridge-search	3 / 5	3 / 5	3 / 5	4 / 5	3 / 5	3 / 5	63 / 100	preview	OK
5	trip-planner	2 / 5	2 / 5	3 / 5	2 / 5	2 / 5	2 / 5	45 / 100	preview	OK
6	weather-current	5 / 5	3 / 5	4 / 5	4 / 5	5 / 5	4 / 5	77 / 100	preview	OK
7	product-card	5 / 5	4 / 5	4 / 5	5 / 5	4 / 5	4 / 5	83 / 100	preview	OK
8	workout-plan	2 / 5	2 / 5	2 / 5	2 / 5	2 / 5	2 / 5	40 / 100	preview	OK

Details

Result 1

• Example: recs
• Dimension: visual-correctness
• Visual correctness: 2 / 5
• GEQI dimensions:
  • Usability & Interaction: 2 / 5 (30%)
  • Visual & Aesthetics: 3 / 5 (25%)
  • Consistency & Standards: 2 / 5 (15%)
  • Architecture & UX Writing: 2 / 5 (15%)
  • Accessibility & Performance: 2 / 5 (15%)
• Task: The A2UI playground preview should show date-night dining recommendations for Moonlight Terrace, Pinewood Bistro, and Sea Breeze Kitchen.

Result 2

• Example: cast-grid
• Dimension: visual-correctness
• Visual correctness: 5 / 5
• GEQI dimensions:
  • Usability & Interaction: 3 / 5 (30%)
  • Visual & Aesthetics: 4 / 5 (25%)
  • Consistency & Standards: 5 / 5 (15%)
  • Architecture & UX Writing: 5 / 5 (15%)
  • Accessibility & Performance: 4 / 5 (15%)
• Task: The A2UI playground preview should show a cast grid for the short film Night Notes, including Lin Xia and Zhou Ning cast cards.

Result 3

• Example: citywalk-list
• Dimension: visual-correctness
• Visual correctness: 2 / 5
• GEQI dimensions:
  • Usability & Interaction: 3 / 5 (30%)
  • Visual & Aesthetics: 3 / 5 (25%)
  • Consistency & Standards: 2 / 5 (15%)
  • Architecture & UX Writing: 2 / 5 (15%)
  • Accessibility & Performance: 3 / 5 (15%)
• Task: The A2UI playground preview should show weekend citywalk coffee picks with Rooftop Brew Room, Corner Canvas Lab, and Late Sun Roastery.

Result 4

• Example: fridge-search
• Dimension: visual-correctness
• Visual correctness: 3 / 5
• GEQI dimensions:
  • Usability & Interaction: 3 / 5 (30%)
  • Visual & Aesthetics: 3 / 5 (25%)
  • Consistency & Standards: 4 / 5 (15%)
  • Architecture & UX Writing: 3 / 5 (15%)
  • Accessibility & Performance: 3 / 5 (15%)
• Task: The A2UI playground preview should show refrigerator search results with Siemens, Hualing, Haier, and Midea product cards.

Result 5

• Example: trip-planner
• Dimension: visual-correctness
• Visual correctness: 2 / 5
• GEQI dimensions:
  • Usability & Interaction: 2 / 5 (30%)
  • Visual & Aesthetics: 3 / 5 (25%)
  • Consistency & Standards: 2 / 5 (15%)
  • Architecture & UX Writing: 2 / 5 (15%)
  • Accessibility & Performance: 2 / 5 (15%)
• Task: The A2UI playground preview should show a Kyoto 48-hour trip planner with Day 1 and Day 2 itinerary sections, including Monkey Park Viewpoint.

Result 6

• Example: weather-current
• Dimension: visual-correctness
• Visual correctness: 5 / 5
• GEQI dimensions:
  • Usability & Interaction: 3 / 5 (30%)
  • Visual & Aesthetics: 4 / 5 (25%)
  • Consistency & Standards: 4 / 5 (15%)
  • Architecture & UX Writing: 5 / 5 (15%)
  • Accessibility & Performance: 4 / 5 (15%)
• Task: The A2UI playground preview should show the current weather for Austin, TX, including clear skies with light breeze.

Result 7

• Example: product-card
• Dimension: visual-correctness
• Visual correctness: 5 / 5
• GEQI dimensions:
  • Usability & Interaction: 4 / 5 (30%)
  • Visual & Aesthetics: 4 / 5 (25%)
  • Consistency & Standards: 5 / 5 (15%)
  • Architecture & UX Writing: 4 / 5 (15%)
  • Accessibility & Performance: 4 / 5 (15%)
• Task: The A2UI playground preview should show a Wireless Headphones Pro product card with a visible Add to Cart action.

Result 8

• Example: workout-plan
• Dimension: visual-correctness
• Visual correctness: 2 / 5
• GEQI dimensions:
  • Usability & Interaction: 2 / 5 (30%)
  • Visual & Aesthetics: 2 / 5 (25%)
  • Consistency & Standards: 2 / 5 (15%)
  • Architecture & UX Writing: 2 / 5 (15%)
  • Accessibility & Performance: 2 / 5 (15%)
• Task: The A2UI playground preview should show a weekly workout plan with five days from Monday Ramp-Up through Friday Conditioning.

Workflow run