[nan-yu]

Stacked on #3862. Review the top eleven commits: feat(typescript): 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 #3862 lands and the open questions below are settled.
Part of #3535.

Description

#3862 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 #3862 into this PR in every SDK (Python #3939, Dart #3941). The code is the code that was on #3862, renamed to fit RendererToAgentMessageProcessor, with the review fixes below.

1. RendererFunctionCalls in @a2ui/agent, one per conversation. call({catalogId, name, args?, surfaceId?, timeoutMs?, functionCallId?}) checks the call and returns the callRendererFunction message to send and a cancellable promise of the result, as a tuple or by name. resolve settles the matching promise with the renderer's value, or rejects it with A2uiRpcError carrying the renderer's code. It returns true when it settled or failed a pending call, and false when the functionCallId isn't pending (unknown, late or a duplicate).

2. A call times out after DEFAULT_RENDERER_CALL_TIMEOUT_MS (30 seconds, as on the renderer side) unless defaultTimeoutMs (which null disables) or timeoutMs says otherwise. Cancelling a call rejects it with CANCELLED and frees its slot. Unknown, duplicate and late responses are ignored, and resolve returns false for them. maxPending limits the calls in flight (TOO_MANY_PENDING), and dispose rejects the pending calls with CANCELLED and refuses later calls with DISPOSED.

3. @a2ui/web_core gets RpcErrorCode.TOO_MANY_PENDING.

4. How it plugs into the processor: resolve is a bound function, passed 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(typescript): agent functions and RendererToAgentMessageProcessor #3862 doesn't change:

   const calls = new RendererFunctionCalls({defaultTimeoutMs: 10_000});
   const messages = new RendererToAgentMessageProcessor({
     catalogs: [catalog],
     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 (INVALID_FUNCTION_CALL), like an empty catalogId.
2. An empty surfaceId counts as omitted: the message leaves it out.
3. A malformed rendererFunctionResponse that carries a pending call's functionCallId fails that call right away with UNKNOWN_ERROR, instead of leaving it to time out.
4. The test for settling a call checks that its timer is cleared (vi.getTimerCount() drops to 0), 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. Each instance keeps its pending calls in memory, so a response must reach the instance that made the call, over a connection that stays open such as a WebSocket. A stateless multi-replica server would handle rendererFunctionResponse in its own onRendererFunctionResponse callback instead. The README says so.

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 Dart.

Changes after the latest review: Review: removed the seconds-based DEFAULT_RENDERER_CALL_TIMEOUT; one consolidated CHANGELOG entry with the #3940 link, and the link on TOO_MANY_PENDING. Aligned with #3939 and #3941: resolve fails a pending call with UNKNOWN_ERROR for error: null, neither value nor error, extra keys or another version; a late response after dispose() settles nothing; the conformance runner enforces the closed RendererCallError and RendererCallsBuildError shapes.

Tests

1. renderer-function-calls.test.ts: options and call validation (including an empty name), duplicate IDs and maxPending, tuple and named results, cancellation, an empty surfaceId, ignored responses, a malformed response that fails its pending call, timers cleared on settle, timeouts and dispose, null defaultTimeoutMs, resolve as the processor's onRendererFunctionResponse, and what resolve returns for pending and other responses. Fake timers are reset in an afterEach hook.
2. renderer-function-calls.test.ts (conformance) 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.
3. yarn --cwd typescript/agents/a2ui_agent build && yarn --cwd typescript/agents/a2ui_agent test && yarn --cwd typescript/agents/a2ui_agent lint && yarn --cwd typescript/agents/a2ui_agent format:check: 1428 passed, 69 skipped.

[gemini-code-assist]

Code Review

This pull request introduces the "RendererFunctionCalls" class to manage agent-to-renderer function calls, handling pending calls, timeouts, cancellations, and response correlation, alongside adding the "TOO_MANY_PENDING" error code to "RpcErrorCode". The review feedback suggests refactoring the unit tests to use an "afterEach" hook for resetting fake timers instead of wrapping assertions in redundant "try...finally" blocks, which reduces boilerplate and prevents test pollution.

[gspencergoog]

This change adds RendererFunctionCalls to @a2ui/agent (and RpcErrorCode.TOO_MANY_PENDING to @a2ui/web_core) for v1.0 agent-to-renderer function calls (callRendererFunction -> rendererFunctionResponse), complete with pre-flight catalog permission and JSON argument validation, timeouts, cancellation, disposal, and 78 unit tests plus the 30-case conformance runner. Before merging, remove the unused seconds-based DEFAULT_RENDERER_CALL_TIMEOUT = 30.0 constant (which creates a unit-mismatch hazard alongside millisecond-based defaultTimeoutMs and timeoutMs options) and consolidate the ## Unreleased changelog entries with [#3940] pull request links.

_{🤖 Agent-generated}

[gspencergoog]

This pull request adds RendererFunctionCalls to @a2ui/agent and RpcErrorCode.TOO_MANY_PENDING to @a2ui/web_core to support v1.0 agent-to-renderer function calls (callRendererFunction and rendererFunctionResponse), along with unit and conformance tests, README usage documentation, and changelog entries. All Round 1 review threads have been resolved (DEFAULT_RENDERER_CALL_TIMEOUT removed, changelog entries consolidated with #3940 links, and response validation tightened), and all CI checks pass.

_{🤖 Agent-generated}