feat(toolchain): add agent-native developer toolchain (headless CLI, Lit render engine, FastMCP server, host profiles)

[weichunglow2024]

Summary of Contribution

This pull request introduces the complete Agent-Native Developer Toolchain for A2UI, bridging the critical developer experience (DX) gap between declarative UI protocol authoring and real-world agent/CI workflows.

It equips human developers and AI coding agents (Claude, Gemini, Cursor, Copilot) with an offline, ground-truth perception-action loop:

1. Headless Developer CLI (a2ui):
   • a2ui check <file>: Full 3-tier validation (JSON Schema Draft 2020-12, component reference graph integrity, and topological recursion checks) with difflib fuzzy suggestions for misspelled components or properties.
   • a2ui catalog describe <catalog>: Formatted tables and JSON schema introspection for component inventories, required props, and reference hierarchy.
   • a2ui catalog diff <left> <right>: Structural delta auditing between catalogs or versions.
2. Hermetic Headless Render Engine (a2ui render --png):
   • Compiles declarative JSON payloads to pixel-perfect PNG images in <200ms using Playwright and an offline, pre-compiled standalone @a2ui/lit bundle (413.5 KB).
   • Zero web server or network connection required; loads directly via file://.
   • Multi-pass whenSettled reactive lifecycle settling loop to prevent visual flakiness.
3. FastMCP Perception-Action Server (a2ui-mcp):
   • Built on fastmcp (stdio transport) exposing 4 core tools: a2ui_list_components, a2ui_validate, a2ui_render (native MCP image streaming), and in-memory a2ui_simulate_action.
4. Declarative Host Target Profiles (--target <profile>):
   • Portable YAML schema enforcing wire protocol versions, required MIME types, composite catalog schemas, and host quirks (gemini-enterprise.yaml).

---

Test Coverage & Verification

• 216 / 216 automated tests passing (0 failures, 0 skips):
  • agent_sdks/python/a2ui_agent/tests/cli/: 38 unit tests passing
  • agent_sdks/python/a2ui_agent/tests/render/: 30 render and visual fidelity tests passing
  • tools/a2ui_mcp/tests/: 69 FastMCP unit and adversarial tests passing
  • tests/e2e/: 79 opaque-box end-to-end tests passing
• Independent Model Verification:
  • Full programmatic audit executed by Anthropic Claude Sonnet 5 (claude-sonnet-5 on Vertex AI) confirming all acceptance criteria with OVERALL AUDIT DISPOSITION: PASS (documented in AUDIT_REPORT.md).
• Hygiene & Standards:
  • Formatted cleanly via pyink (0 files reformatted across 360 files).
  • Apache 2.0 / Google LLC copyright headers on all new files.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive developer toolchain CLI and a FastMCP server for A2UI, enabling payload validation, catalog inspection/comparison, headless rendering via Playwright, and action simulation. Feedback on the changes highlights a potential type mismatch bug when validating component IDs in the target profile schema, a potential AttributeError in the MCP server's action simulation if node properties are not a dictionary, an unused variable in the rendering engine, and a minor type-hinting style improvement.

[gemini-code-assist]

There is a potential type mismatch bug when validating component IDs. canvas_ids contains string-coerced IDs (via str(cid)), but root_comps and children_ids use raw IDs (which could be int or other types). Comparing them directly (e.g., r.get("id") == cid) will fail if one is an integer and the other is a string. Coercing all IDs to strings during these checks ensures robust validation.

Suggested change

	root_comps = [
	c
	for c in components
	if isinstance(c, dict) and c.get("id") not in children_ids
	]
	# Quirk check 1: Canvas must not be a child component
	for cid in canvas_ids:
	if cid in children_ids:
	errors.append(
	"Quirk 'side-panel-requires-canvas-root' violated: Component"
	f" 'Canvas' (id: '{cid}') is nested as a child component in"
	f" surface '{surface_id}'; Canvas must be the root component."
	)
	elif root_comps and not any(r.get("id") == cid for r in root_comps):
	root_comps = [
	c
	for c in components
	if isinstance(c, dict) and str(c.get("id")) not in children_ids
	]
	# Quirk check 1: Canvas must not be a child component
	for cid in canvas_ids:
	if cid in children_ids:
	errors.append(
	"Quirk 'side-panel-requires-canvas-root' violated: Component"
	f" 'Canvas' (id: '{cid}') is nested as a child component in"
	f" surface '{surface_id}'; Canvas must be the root component."
	)
	elif root_comps and not any(str(r.get("id")) == cid for r in root_comps):

[gemini-code-assist]

The variable props is assigned node.props.value or {}, but there is no type verification to ensure it is actually a dictionary. If node.props.value is a non-dictionary type, calling props.get or props.items later will raise an AttributeError and crash the server. It is safer to verify the type first.

Suggested change

	props = node.props.value or {}
	props = node.props.value if isinstance(node.props.value, dict) else {}

References

1. When validation checks or function arguments can be represented as either a dictionary (named) or a list (positional), always verify the type (e.g., using isinstance(args, dict)) before performing key-based lookups or assignments to prevent TypeError crashes.

[gemini-code-assist]

The type hint Set is used here but is not imported from typing. Since from __future__ import annotations is enabled, you can use the standard lowercase set[str] instead of Set[str], which is more idiomatic in modern Python (3.9+) and does not require any imports.

Suggested change

	seen_messages: Set[str] = set()
	seen_messages: set[str] = set()

[gemini-code-assist]

The variable effective_timeout_sec is calculated but never used in the render method. Consider removing it to keep the code clean.

References

1. When refactoring or fixing issues in code, prefer completely removing dead code or redundant checks rather than modifying them with more complex conditional logic.