Client-Tool Registry and Render Hints#

Overview#

The client-tool registry is the dispatch mechanism that routes browser-fulfilled ("client") tools in the agent chat UI to the correct React widget. It lives in web/oss/src/components/AgentChatSlice/components/clientTools/ and was introduced as part of the initial client-tool round-trip in PR #4934 1, then extended with render.kind-based dispatch and the elicitation form in PR #5155 2.

The central guarantee the registry provides: a parked client-tool call never causes a run to hang silently. Every unrecognized tool falls through to a generic fallback that auto-settles, allowing the run to resume 1.

Three-Tier Dispatch Precedence#

registry.tsx resolves the widget for a tool part using three-tier precedence 2:

• render.kind is the primary dispatch axis — a required wire field on all new interaction kinds. New tools such as request_input (the elicitation emitter) are identified exclusively through their render kind 2.
• toolName is the legacy fallback. request_connection still resolves by bare name for v1 wire compatibility — the v1 wire predated the render-kind guarantee 1.
• UnhandledClientTool is the generic fallback for any tool that matches neither table. It auto-settles the part so the run resumes (see Auto-Settlement).

meta.ts computes the renderKind and toolName properties used by the registry from a ToolUIPart and the message-scoped render map 2.

Render Hint Wire Transport#

Because AI SDK v6 tool chunks are strict objects that drop inline fields, render.kind cannot travel inline with the tool-call part 2. Instead it arrives as a sibling data-render message part, a separate part containing a { toolCallId, render } record.

renderMap.ts (added in PR #5155) provides two utilities 2:

• buildRenderMap(parts) — iterates all message parts, filters data-render entries, and returns a Map<toolCallId, RenderHintLike>. This per-message map is the single source of truth for render hints throughout a turn.
• renderKindFor(part, renderMap) — checks the inline render.kind field first (for future SDK versions), then falls back to the map.

Both the registry (registry.tsx) and the resume predicate (agentApprovalResume.ts) consult the same render map, ensuring consistent tool classification across rendering and resume logic 2.

AI SDK v6 stream
  ├─ tool-call part { toolCallId, toolName, args }
  └─ data-render part { toolCallId, render: { kind: "elicitation", ... } }
          │
          ▼
    buildRenderMap()
          │
          ├──▶ registry.tsx → widget lookup
          └──▶ agentApprovalResume.ts → resume predicate

Auto-Settlement and Graceful Degradation#

Two layers of graceful degradation prevent runs from hanging:

Unknown tools — UnhandledClientTool.tsx (introduced in PR #4934) renders a neutral "not handled by this client" surface and immediately auto-settles the part with a non-error output 1. This means a platform operator can emit a new client-tool kind that the frontend doesn't yet recognize, and the run still progresses.

Invalid payloads — ElicitationWidget.tsx handles malformed elicitation payloads by auto-settling with an errorText prefix ("elicitation: unsupported payload — ..."). A retry-cap flag (degradedEarlierInTurn) prevents the settle→resume→re-emit loop from repeating: a second degradation parks the widget with a visible notice rather than looping indefinitely 2.

The settlement flow in both cases:

1. Widget calls settle(...) via the onClientToolOutput callback
2. addToolOutput in the panel matches the parked tool by toolCallId
3. agentShouldResumeAfterApproval detects the settled result and triggers auto-resume

Resume Predicate and Queue Gating#

agentApprovalResume.ts contains the core logic that integrates render hints into the run-resume decision 2 1:

• isClientTool(part, renderMap) — classifies a tool part as a client tool when renderKindFor() returns a known kind or the tool name is in CLIENT_TOOL_NAMES. This dual check preserves backward compatibility with v1 wire.
• isClientToolResult(part, renderMap) — identifies a settled client-tool part (output-available or output-error). When agentShouldResumeAfterApproval detects such a result, it signals immediate auto-resume.

Queue gating — agentMessageQueue.ts uses canReleaseQueuedMessage() to hold the outbound message queue while a pending client-tool interaction exists 2. This prevents a queued user message from injecting itself into the transcript before the widget has settled, keeping the conversation coherent.

Key guard 1: An approval-gated tool that was approved and then ran also lands in output-available with providerExecuted falsy. The resume predicate must not treat this as a client-tool result; the approval metadata guard is load-bearing.

Unit tests covering the resume predicate and queue gating live in renderMap.test.ts (233 lines, added in PR #5155) and agentApprovalResume.test.ts 2.

Key Files Reference#