(internal) Feat/a2h prototypes

[zeroasterisk]

⚠️ Not for Merge — Discussion Only

This PR exists as a convenient place to review and discuss the A2H × A2UI prototype exploration. It is not intended to be merged into main.

What's here

• 5 A2H intent prototypes, each in two versions (v0.9.0 current spec vs v0.9.1 with proposed improvements)
• A design doc (DESIGN.md) with findings, comparison metrics, and spec recommendations
• A helper library prototype (lib/a2h-a2ui.js)

Key finding

A2UI v0.9 covers ~85% of A2H needs today. Four small spec additions — visible binding, Button label prop, ProgressIndicator, KeyValue — would close most remaining gaps.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive set of prototypes and a design document for integrating A2H (Agent-to-Human) with A2UI, covering five interaction intents and proposing enhancements to the A2UI specification. A critical finding from the security audit is a high-severity Prototype Pollution vulnerability in the renderer logic of the p3-guided-input and p5-wizard prototypes, stemming from unsafe handling of data paths in component JSON, which could allow an attacker to pollute the global Object.prototype. A medium-severity prototype manipulation issue was also found in the component collection logic. From a code quality perspective, key areas for improvement include refactoring state management in the helper library to avoid global state, correcting data binding logic for input components, and fixing implementation bugs in the demo and prototype pages. On a positive note, the renderers consistently use textContent for displaying text, mitigating direct Cross-Site Scripting (XSS) risks.

[gemini-code-assist]

The setPath function is vulnerable to Prototype Pollution. It recursively traverses the obj based on the path provided in the component JSON. If the path contains sensitive keys like __proto__, constructor, or prototype, it can be used to pollute the global Object.prototype. Since the component JSON is intended to come from an AI agent (which is an untrusted source), this allows an attacker to manipulate the renderer's environment, potentially leading to Denial of Service or Cross-Site Scripting.

Suggested change

	function setPath(obj, path, value) {
	const parts = path.split('/').filter(Boolean);
	let cur = obj;
	for (let i = 0; i < parts.length - 1; i++) {
	if (!(parts[i] in cur)) cur[parts[i]] = {};
	cur = cur[parts[i]];
	}
	cur[parts[parts.length - 1]] = value;
	}
	function setPath(obj, path, value) {
	const parts = path.split('/').filter(Boolean);
	let cur = obj;
	for (let i = 0; i < parts.length - 1; i++) {
	const key = parts[i];
	if (key === '__proto__' || key === 'constructor' || key === 'prototype') return;
	if (!Object.prototype.hasOwnProperty.call(cur, key)) cur[key] = {};
	cur = cur[key];
	}
	const lastKey = parts[parts.length - 1];
	if (lastKey !== '__proto__' && lastKey !== 'constructor' && lastKey !== 'prototype') {
	cur[lastKey] = value;
	}
	}

[gemini-code-assist]

The deepSet function is vulnerable to Prototype Pollution. It recursively traverses the obj based on the path provided in the component JSON. If the path contains sensitive keys like __proto__, constructor, or prototype, it can be used to pollute the global Object.prototype. Since the component JSON is intended to come from an AI agent (which is an untrusted source), this allows an attacker to manipulate the renderer's environment, potentially leading to Denial of Service or Cross-Site Scripting.

Suggested change

	const parts = path.split('/').filter(Boolean);
	let cur = obj;
	for (let i = 0; i < parts.length - 1; i++) {
	if (!(parts[i] in cur)) cur[parts[i]] = {};
	cur = cur[parts[i]];
	}
	cur[parts[parts.length - 1]] = val;
	}
	function deepSet(obj, path, val) {
	const parts = path.split('/').filter(Boolean);
	let cur = obj;
	for (let i = 0; i < parts.length - 1; i++) {
	const key = parts[i];
	if (key === '__proto__' || key === 'constructor' || key === 'prototype') return;
	if (!Object.prototype.hasOwnProperty.call(cur, key)) cur[key] = {};
	cur = cur[key];
	}
	const lastKey = parts[parts.length - 1];
	if (lastKey !== '__proto__' && lastKey !== 'constructor' && lastKey !== 'prototype') {
	cur[lastKey] = val;
	}
	}

[gemini-code-assist]

The uid function relies on a global _counter. This is problematic for a library as it introduces a shared global state. If multiple parts of an application create surfaces, they will all increment the same counter, which can lead to unpredictable component IDs and potential collisions if not managed carefully. The presence of resetIds suggests awareness of this for testing, but it's not a robust solution for production use.

A better approach is to scope the counter to each surface generation. This could be achieved with a factory function or a class that encapsulates the counter state.

function createIdGenerator(prefix) {
  let counter = 0;
  return (suffix) => `${prefix}-${suffix}-${++counter}`;
}

// Then, inside each `create...Surface` function:
// const uid = createIdGenerator('auth');
// const descId = uid('desc');

[gemini-code-assist]

The current implementation for TextField and ChoicePicker components has two issues:

1. The value property is only bound to a data model path if an initial f.value is provided. For two-way data binding to work, the value should always be bound to its path in the data model, regardless of whether an initial value is present. The initial value itself should be set in the dataModel object passed to the function.
2. A non-standard data property is being added with the path. This property is not part of the A2UI v0.9 spec for these components and is not used by the renderers in the prototypes.

To fix this, the value property should always be set to { path: f.path }, and the data property should be removed.

    if (f.type === 'select') {
      fieldComponents.push({
        id: fieldId,
        component: 'ChoicePicker',
        options: (f.options || []).map(o => typeof o === 'string' ? { label: o, value: o } : o),
        value: { path: f.path },
      });
    } else {
      fieldComponents.push({
        id: fieldId,
        component: 'TextField',
        placeholder: f.label,
        value: { path: f.path },
      });
    }

[gemini-code-assist]

The renderers for TextField and ChoicePicker are missing two-way data binding. They set the initial value from the data model but don't update the model when the user interacts with the input. As a result, when the form is submitted, the initial data is sent, not the user's input, which makes the 'Fill & submit' feature of the COLLECT prototype non-functional.

You should add event listeners (input for TextField, change for ChoicePicker) to update the dataModel as the user makes changes. You can see a working example of this in p5-wizard/index.html.

[gemini-code-assist]

The components object is initialized as a plain object and then populated using component IDs provided in the JSON. If a component has an id of __proto__, it will overwrite the prototype of the components object. While the impact is limited in this specific demo, this pattern can lead to unexpected behavior or security issues if the object is used in a way that relies on its prototype chain. Using Object.create(null) ensures that the object has no prototype and is safe from such manipulation.

Suggested change

	let components = {};
	let components = Object.create(null);