Commerce UI Tools

Presentation tools

Paths are in the reference repo: commerce_common/ is commerce-common/commerce_common/, shopping_agent/ is shopping-agent/core/shopping_agent/, merchant_agent/ is merchant-agent/core/merchant_agent/.

The contract

• A component is a tool. The model's arguments carry its judgment: which ids, in what order, the reason or the note for each, what to compare on. The server joins every fact (title, price, image, metric value, change record) from records tools returned this session, so the frontend never renders a model-authored value.
• One spec per component: PresentationComponent in commerce_common/presentation.py names the tool, the component string the host renders, the payload_model that validates the arguments (each role's tools/presentation.py), and the enrich hook (each role's enrichment.py, collected in PRESENTATION_COMPONENTS).
• run_presentation in commerce_common/presentation.py is the one runner: validate, enrich, emit the ui event. The model reads the executor's displayed_text plus the hook's notes; the enriched payload goes to the host only.
• An enrich hook drops ids without provenance and appends a note naming them; with nothing left it raises PresentationRefused, which comes back as a held call when it names a gate and as an error otherwise.
• Shopping joins from ShoppingSessionState.seen_products, the cart, or an order read; merchant joins from MerchantSessionState.latest_snapshot, seen_series, seen_campaigns, seen_analyses, seen_listings, and seen_changes. enrich_change_preview also removes model text whose currency or weekday disagrees with the change record.
• Composition rules (which component ends a turn, text carries the reasoning, cards carry the data) are static prompt material; each component's when-to-use line is its tool description (commerce-architecture's layer table).

Suggestions

• present_suggestions is the one tool that carries the turn's chips, up to four; the model calls it in the same round as the turn's last component, or after its text when the turn has none, and a tapped chip is sent as the next user message. No other payload, built-in or extension, carries chips.
• sanitize_suggestion_chips in commerce_common/fencing.py runs on PresentSuggestionsPayload: invisible and control characters out, whitespace collapsed, empties dropped, 80 characters each, four at most. The payload fails when no chip survives sanitizing.
• A round of clean presentation calls that includes present_suggestions ends the turn (round_closes_turn in commerce_common/turn.py, close_on_presentation in the config): the Messages API loop stops there, and the Agent SDK runtimes stop through a PostToolBatch hook (close_on_presentation_hook in commerce_common/agent_sdk.py). Under host approval the merchant prompt says no chip approves or applies.

Streaming

The event list is the docstring of commerce_common/streaming.py; to_sse frames each event and a host ignores types it does not know. ui carries one enriched component, ui_partial the same while its call still streams, cart_update the whole cart after a cart write, and change_update a change record after it moved. outcome_events in commerce_common/turn.py stamps each ui event with its call id as stream_id and follows it with the tool_result, whose status is ok, error, or blocked. Every tool that is not a presentation tool may take a status argument first (with_status in commerce_common/execution.py): a few words for the person waiting, which the executor drops before the call runs and the runtime emits as the tool_call event's label; the web layer shows it as the activity line. The MCP servers build their tools without it. The Agent SDK runtimes run the same executor but return the payloads together in result.ui after the turn.