Implement agent 1.0. - #3242

Contributes to: #2356

Contributes to: #3100

Summary

#3233 added the protocol v1.0 API to the Dart agent SDK, with stubs that threw UnimplementedError. This PR implements them, so a2ui_agent reads and writes v1.0 in both inference formats (direct JSON and Express). The shared conformance suites under conformance/agent now run as written in v1.0, as well as lowered to v0.9, and the Dart harnesses no longer skip any case as a known gap.

It also makes streaming direct JSON cost time in proportion to the payload: parseChunk used to read and check the whole block again on every chunk, which took 1.36 s for a 6.4 KB payload in 16-byte chunks and now takes about 0.1 s. See Performance.

Changes in a2ui_core

• MessageProcessor.forAgent checks a callRendererFunction instead of throwing (processor.dart). The surface must exist, the catalog the call names must be held and target the message's version, and that catalog must declare the function, let the agent call it, and accept its arguments. A function with requiresUserActivation is accepted only when processMessages is given isUserActivated. Each of these throws A2uiValidationError, since a renderer answers each with INVALID_FUNCTION_CALL.
• PayloadValidator.validateFunctionCall (validator.dart) checks a call written on its own, such as the callFunction of a callRendererFunction. The call, and each call nested in its arguments, is checked against the catalog its catalogId names, and may hold only the fields FunctionCall allows. A catalogId that is not a string is rejected. forAgent and the agent's MessageReader both use it.
• PayloadValidator.validateFunctionArgs is public (validator.dart), so the agent can check a call nested in a component against the catalog the call names rather than the component's.
• checkDuplicateComponentIds is exported (component_graph.dart), with an earlier argument for the ids of earlier batches, so the agent can check one message's components in several batches as they stream.
• A MessageProcessor whose validationConfig allows dangling references, and orphan components or a missing root, checks an updateComponents without walking the whole surface (component_model.dart). The surface's component model keeps a bound on each component's chain of references (_GraphBound), and walks only the components an update reaches when the bound shows there is no cycle and no chain past the depth limit. Otherwise it walks the whole surface as before. The bound holds only while nothing has changed the model since the processor applied the batch it was found for.
• A processor skips the composition checks when no catalog its surface draws on declares allowedParents or allowedChildren (processor.dart), rather than building every component's JSON for each update.

Changes in a2ui_agent

Direct JSON

• A shared MessageReader (message_reader.dart) checks each v1.0 component and function call against the catalog it names, else its surface's catalog. For a surface the payload does not create, a component that names no catalog is checked against the first catalog that declares it. The parser reads with catalogs linked by linkCatalogs, so a cross-catalog $ref from #3230 resolves.
• A PayloadChecker (payload_checker.dart) applies the messages for the surfaces a payload creates through MessageProcessor.forAgent. compile (parser.dart) then rejects a message that comes before its surface's createSurface, and a created surface with no root, a reference to a missing component, a component the root does not reach, or a cycle. A surface the payload only updates may hold components from earlier responses, so those checks skip it, as in the Python SDK.
• The streaming parser holds a v1.0 component back until its object closes, since its catalogId may come last, and checks what has arrived, so a cycle is never emitted. An updateComponents whose closed components fail the check raises on the chunk that closes them. A string cut between the two halves of an escaped surrogate pair is cut before the pair rather than healed with U+FFFD (json_reader.dart).
• The streaming parser reads and checks only what each chunk adds:
  • _StreamedChecks (parser.dart) keeps one PayloadChecker, and the surfaces read so far, for the whole block. A message is read and checked once, when it closes. A growing updateComponents is checked only for its new components, and for its last one again when components are not held back, with duplicate ids checked across the batches. A growing updateDataModel is checked again whole when it changes.
  • readPartialMessages takes a PartialReadCache (json_reader.dart): a list or map that closed is not read again, and a list still open is read on from its last item that closed (L308-L371). It reads the block in place between two offsets rather than a copy.
  • The scan for the close tag goes on from where the last chunk's scan stopped (_BlockScanner), and a trailing markdown fence is found by reading back from the end (_trailingFenceStart) rather than with a regular expression that tried every offset of the block.

Express

• The compiler (compiler.dart) writes the v1.0 message shapes: createSurface carries the components and data model, and bindings and calls use @path and @call. A component, function call or check names its catalog with a catalogId argument, which a name declared by several catalogs needs, and which must be a string literal (L766-L788). A function call written as a statement of its own compiles to a callRendererFunction (L433-L483), with the id call_<n> or the one a functionCallId argument gives, and may name the variables of the surface it is written in, the default surface included (L171-L176). Two calls of a block may not share an id (L103-L124), and an inline component may not take an id another component has (L972-L986). The output goes through the same MessageReader as direct JSON.
• The decompiler (decompiler.dart) writes catalogId only where the compiler could not tell the catalog from the name alone, and functionCallId only when the id is not call_<n>. A call that belongs to no active catalog throws A2uiValidationError rather than being written as a map the compiler rejects. It writes a single check without brackets, a multiline string with backslashes as a raw triple-quoted string, and an updateDataModel below the root as assignments at its path, as conformance/agent/express/decompiler.yaml expects.
• The prompt (prompt_generator.dart) explains how to name a catalog when several are active and lists the names that need one. When callRendererFunction is allowed, it lists the functions the agent may call. It also carries each catalog's instructions, with their JSON examples rewritten in Express, and each function's description (L331-L355).

Request processor

• validatePayloads (validation.dart) throws A2uiValidationError for a v1.0 component or call that names a catalog that is not active, then runs the payload through MessageProcessor.forAgent. It skips a component's metadata, as the processor does.

Changes in a2ui_flutter

• video_player is ^2.11.1 rather than ^2.14.1. Version 2.14.1 needs Dart 3.12 and Flutter 3.44, above the package's declared Dart 3.10 and Flutter 3.38, and 2.11.1 is the oldest release that genui ^0.8.0, another package of the workspace, accepts.

Performance

Streaming a payload of one createSurface and one updateComponents with a Column and N Text children, in 16-byte chunks, on a MacBook:

Before, each chunk read the whole block again, replayed every message through a new MessageProcessor, and ran a regular expression over the block. Doubling the payload now about doubles the time; most of the 0.10 s for 100 components is the first run's warm-up. #3285 proposes performance tests in CI that would catch a regression like this one.

Decisions to review

• allowedCallers is enforced: a response may call only a function marked agentOnly or rendererOrAgent. The default is rendererOnly, so the v1.0 test catalogs set rendererOrAgent on the functions the tests call. parseResponse enforces it; a parser's compile and parseChunk check only a call's arguments, as the README says.
• A v1.0 parser always holds streamed components back. bufferIncompleteComponents now applies only to catalogs before v1.0.
• In every version, a streamed message other than updateComponents and updateDataModel is emitted once, after its object closes, and the messages after it wait until then (parser.dart). Before, a createSurface or callRendererFunction was emitted while it grew, so a renderer could run a call twice, the first time with partial arguments.
• A streamed message that grows is emitted again with the component maps it emitted before, as the same objects, rather than with new copies.
• The graph check only skips the walk of the whole surface when a bound proves the walk would pass, so it never changes which updates fail or with which error. It applies to a processor that allows dangling references and orphans or a missing root, as the agent's checks of a payload still arriving do; a stricter config walks the whole surface as before. A catalog that declares composition constraints still has them checked against the whole surface on every update, which keeps their error order and rule precedence as they were.
• Direct JSON compile checks the surfaces a payload creates whole. The basic catalog example 31_incremental-dashboard.json leaves its loading placeholders unreachable, so specification_round_trip_test.dart compiles its later updates as payloads of their own, as later responses would send them.
• The Express prompt has a rule for function calls written as statements of their own, and it names the functions that may be called this way. The Python prompt has no rule for them.
• The Express compiler rejects two standalone calls with the same functionCallId. The Python compiler gives both the same id.
• A check's default message is now Required check failed, without the trailing period, as in Python, TypeScript and the suite.
• An updateDataModel below the root decompiles to assignments that compile to an update of the root, as the suite expects, which replaces the rest of the data model. An update of a list item, such as /restaurants/3 in 00_incremental.json, still throws, since the assignment would turn the list into a map.
• Four cases in multi_catalog_formats.yaml put a function call in Chart.caption, which custom_catalog_v1_0.json types as a plain string. A renderer would reject the call there, and so does this SDK. The cases now place the call in Text.text, a DynamicString, and test the same catalog resolution. The inline catalogs of two cases also referenced common.json, which after feat(agent,core): support cross-catalog $ref resolution across peer catalogs #3230 is an unknown document that a2ui_core rejects. They now reference common_types.json. The Python and TypeScript SDKs pass the edited suite.

Testing

• flutter test: a2ui_agent 1021 passed and 70 skipped, a2ui_core 1798 passed and 5 skipped, a2ui_flutter 309 passed, the last also with video_player 2.11.1, and a2ui_cli 35 passed. The skips are v0.8 cases and cases v0.9 cannot state.
• protocol_v1_0_test.dart covers negotiation, both formats with one catalog and with several, streaming, including a repeated id and a cycle that a later chunk closes, and A2uiRequestProcessor. processor_for_agent_test.dart covers the callRendererFunction check. The v1.0 group of specification_round_trip_test.dart round-trips every v1.0 basic catalog example through direct JSON, and all but 00_incremental.json through Express.
• json_reader_test.dart reads every start of several payloads with and without a PartialReadCache and expects the same messages. component_graph_bound_test.dart applies random batches to two component models, one that keeps the bound and one that walks the whole graph every time, and expects the same verdict and error for every batch; it fails when the bound skips a step.
• flutter analyze --fatal-infos and dart format are clean for the four packages, and Prettier 3.8.4 is clean for the changed Markdown and YAML.
• The Python agent conformance tests for multi_catalog_formats.yaml pass (34 cases), and so do the TypeScript a2ui_agent tests.
• The e2e tests pass against Gemini for v0.9 and v1.0, including direct JSON read as it streams.

Outside this PR

• a2ui_agent uses a2ui_core API that is not released yet. Publishing it needs an a2ui_core release and a higher constraint than ^0.3.0.
• a2ui_core declares Dart 3.5, but it depends on json_schema_builder ^0.1.7, and every release from 0.1.5 needs Dart 3.10, so the package resolves on Dart 3.10 and later only, as a2ui_agent and a2ui_flutter do. a2ui_core declares Dart 3.5 but resolves only on Dart 3.10 and later #3289 tracks the fix.

_{🤖 Agent-generated}