[nan-yu]

Stacked on #3861. Review the top nine commits: feat(dart-agent): call renderer functions from the agent (#3535), followed by the review-fix and conformance commits covering RendererFunctionCalls.resolve declining unknown responses, catalog target checks, the shared validation order, isPending, and routing conformance responses through RendererToAgentMessageProcessor. Draft until #3861 lands and the open questions below are settled.
Part of #3535.

Description

#3861 first shipped the agent's calls to renderer functions (callRendererFunction) together with agent functions, as the Python stack did. The review on #3793 questioned whether in-memory pending calls fit stateless HTTP servers, where the rendererFunctionResponse can arrive in a later request on another replica. To keep agent functions moving, renderer function calls were split out of #3861 into this PR in every SDK (Python #3939, TypeScript #3940). The code is the code that was on #3861, renamed to fit RendererToAgentMessageProcessor, with the review fixes below.

1. RendererFunctionCalls in a2ui_agent, one per conversation. call({required catalogId, required name, args, surfaceId, timeout, functionCallId}) checks the call and returns a record of the CallRendererFunctionMessage to send and a Future of the result. resolve completes the matching future with the renderer's value, or with an A2uiRpcError carrying the renderer's code. It returns true when it settled or failed a pending call, and false otherwise (an unknown, late or duplicate response).

2. A call times out after defaultRendererCallTimeout (30 seconds, as on the renderer side) unless given another timeout; defaultTimeout: null disables the default. Unknown, duplicate and late responses are ignored. maxPending caps the calls pending at once (TOO_MANY_PENDING), and dispose fails the pending calls with CANCELLED and refuses later calls with DISPOSED.

3. a2ui_core gets RpcErrorCode.tooManyPending (TOO_MANY_PENDING), and package:a2ui_agent/a2ui_agent.dart also re-exports CallRendererFunctionMessage. fake_async is a new dev dependency for the timer tests.

4. How it plugs into the processor: pass calls.resolve to RendererToAgentMessageProcessor as onRendererFunctionResponse, so the processor validates the response and hands it over. Since callbacks may return false to decline (from the second review of feat(python-agent): answer agent functions through RendererToAgentMessageProcessor #3793), a response resolve doesn't own, such as one to a call the model wrote, comes back handled: false and can go on to the model. The processor's API from feat(dart): agent functions and RendererToAgentMessageProcessor #3861 doesn't change:

   final calls = RendererFunctionCalls();
   final processor = RendererToAgentMessageProcessor(
     catalogs: catalogs,
     onRendererFunctionResponse: calls.resolve,
   );

5. The README gets a "Calling renderer functions" section, and both CHANGELOGs list the API.

Review fixes from #3793, applied here as in Python:

1. An empty function name is rejected with A2uiRpcError (invalidFunctionCall), like an empty catalogId.
2. An empty surfaceId counts as omitted: the message leaves it out.
3. A malformed rendererFunctionResponse that names a pending call fails that call right away with unknownError, instead of leaving it to time out. One that names no pending call is ignored.
4. The test for settling a call checks that its timer is cancelled (FakeAsync.pendingTimers is empty afterwards), the counterpart of Python's timer.cancelled() assertion.

Open design questions, kept for discussion on #3939:

1. maxPending and the TOO_MANY_PENDING code, which the protocol doesn't define. The agent's own code starts these calls, so a limit may not be needed.
2. Stateless servers. Pending calls live in memory, so this suits an agent that keeps a connection to the renderer open, such as a WebSocket. A stateless multi-replica server would handle rendererFunctionResponse in its own onRendererFunctionResponse callback instead.

Catalog checks (after review on #3793, #3793 (comment)): RendererFunctionCalls takes an optional catalogs argument. With it, call() checks the target before it builds a message, registers a pending call or starts a timer. An unknown catalogId, or a name that isn't one of that catalog's renderer functions (agent functions included), gets UNKNOWN_FUNCTION. A rendererOnly function (or one that leaves out allowedCallers) gets INVALID_FUNCTION_CALL, and so does one with requiresUserActivation: true, since a call from the agent has no user gesture. Two catalogs with the same ID are a catalog error. Without catalogs, nothing changes. The conformance runner supports the new catalogs cases. Checked locally against renderer_function_calls.yaml from #3939: 31/31 (30 cases and the non-empty check). call() runs its checks in the same order in all three SDKs:

1. an invalid timeout
2. disposed
3. an empty given functionCallId
4. a duplicate id
5. max_pending
6. an empty name, then an empty catalogId
7. a name that isn't an identifier
8. the args checks: a JSON object, identifier keys, and JSON values (no NaN or infinity)
9. these catalog checks

Only the instance default timeout can be "no limit". isPending(functionCallId) inspects whether a call is awaiting a response without settling it, matching Python and TypeScript.

Changes after the latest review: Review: _parseResponse reads responses as strict v1.0 (version "1.0", exactly one of value and error, no extra keys), so a malformed response fails a pending call with UNKNOWN_ERROR as in Python and TypeScript; tests updated (a void response sends value: null); the conformance runner enforces the closed RendererCallError and RendererCallsBuildError shapes.

Tests

1. renderer_function_calls_test.dart: constructor checks, the message and its value, void and error results, call validation, duplicate IDs, maxPending, timeouts and dispose, the timer cancelled on settle, an empty name, an empty surfaceId, malformed responses with and without a pending call, resolve plugged into RendererToAgentMessageProcessor, what resolve returns, and a response it declines coming back unhandled from the processor.
2. agent_function_validation_end_to_end_test.dart round-trips both callAgentFunction and callRendererFunction between a core MessageProcessor and the agent. agent_functions_test.dart in a2ui_core checks the TOO_MANY_PENDING code.
3. renderer_function_calls_conformance_test.dart runs conformance/agent/renderer_function_calls.yaml. That suite lands with feat(python-agent): call renderer functions from the agent #3939, so on this branch the runner registers one skipped test saying the suite isn't in the checkout. With the suite from feat(python-agent): call renderer functions from the agent #3939 copied into a copy of this branch, all 30 cases and the non-empty check pass (31 tests), delivering responses through RendererToAgentMessageProcessor and checking calls.isPending.
4. Commands:
   1. cd dart/a2ui_core && dart analyze --fatal-infos && dart test: clean, 2265 passed (20 skips, none in the agent function tests).
   2. cd dart/a2ui_agent && dart analyze --fatal-infos && dart test: clean, 1691 passed. The renderer calls conformance test registers one skipped placeholder until renderer_function_calls.yaml lands with feat(python-agent): call renderer functions from the agent #3939.
   3. dart format --output=none --set-exit-if-changed . is clean in both packages.

[gemini-code-assist]

Code Review

This pull request introduces RendererFunctionCalls to allow agents to call renderer functions and wait for their results, managing timeouts, concurrent call caps, and disposal. It also adds the TOO_MANY_PENDING RPC error code to a2ui_core and includes comprehensive unit, conformance, and end-to-end tests. The review feedback suggests retaining explicit type annotations on loop variables when iterating over non-literal collections in renderer_function_calls.dart and renderer_function_calls_conformance_test.dart to comply with the project's style guidelines.

[gspencergoog]

This pull request adds RendererFunctionCalls in dart/a2ui_agent and RpcErrorCode.tooManyPending in dart/a2ui_core to build outbound v1.0 callRendererFunction messages, validate call inputs and renderer catalog targets synchronously in the shared cross-SDK order, correlate incoming rendererFunctionResponse envelopes, and manage timeouts and disposal. Static analysis, formatting, unit and end-to-end tests, and all 31 conformance cases from conformance/agent/renderer_function_calls.yaml pass, with one schema-alignment fix needed in _parseResponse (and its paired unit test) when resolve is called directly without RendererToAgentMessageProcessor.

_{🤖 Agent-generated}

[gspencergoog]

This pull request adds RendererFunctionCalls in dart/a2ui_agent and RpcErrorCode.tooManyPending (TOO_MANY_PENDING) in dart/a2ui_core to construct outbound v1.0 callRendererFunction messages, validate call inputs and renderer catalog targets synchronously in the shared cross-SDK order, correlate incoming rendererFunctionResponse messages, and manage per-call timeouts and disposal. Both Round 1 review comments (M1 strict v1.0 FunctionResponse validation in _parseResponse and L1 void/malformed response unit test updates) and both earlier style threads have been verified as resolved at HEAD, and dart analyze --fatal-infos and dart test pass with zero issues.

_{🤖 Agent-generated}