@webless/agent 0.10.4 → 0.11.0

package/README.md

@@ -34,6 +34,7 @@ Paste it into your site's HTML, before the closing `</body>` tag. That's the ful
 - Search & Discovery source cards and call-to-action links beneath each answer, retained in the current browser session history. Sources without a usable web URL stay readable; unavailable action links are omitted.
 - Connected actions show task-focused progress and confirmed results. Receipts stay with the answer in the conversation.
 - Long answers keep their beginning visible; source links are collapsed until opened.
+- When a question needs location, the agent can pause and show a precise-location consent toggle above the composer. Location is shared only after browser permission; visitors can continue without it.
 - Page content shifts to make room for the desktop side rail.
 
 ## Preview before you install
@@ -44,6 +45,16 @@ Agent Studio generates a live preview of the agent on your pages, so you can che
 
 `@webless/agent` is published for Webless tooling and internal use. It powers the script bundle served from the console install flow.
 
+### Location-aware tool requests
+
+The built-in widget advertises `locationConsent: "v1"` during bootstrap. A compatible runtime can then pause on `request_location`, which the widget renders as a toggle rather than a generic approval card. Headless clients should set `createAgentClient({ locationConsent: true, ... })` only if they implement that UI and resolve its pending request IDs.
+
+The toggle obtains unrounded coordinates through browser geolocation with `enableHighAccuracy: true`. Its native approval response carries the typed JSON result in `text`; the runtime validates it before returning a structured tool result. Coordinates are not appended to the visitor's chat message or stored as a browser preference. The runtime retains the shared input and tool result in its conversation history.
+
+A No thanks response resolves the native tool with `optionId: "approve"` and `text: '{"status":"declined"}'`, so the paused turn continues without coordinates. Headless implementations must use this structured decision rather than cancelling tool execution.
+
+While enabled, subsequent location tool requests obtain a fresh fix. Turning the toggle off makes later requests continue without sharing. The preference resets with a new conversation. Permission failures leave retry and skip controls, and the client ignores callbacks from a cancelled request. Older runtimes receive a bootstrap retry without the new capability, so existing conversations continue during a rolling deployment.
+
 ## Render a stored conversation in React
 
 `AgentTranscript` reuses the agent's message renderer without connecting to a runtime or creating a session. It renders a snapshot: no composer, feedback, regeneration, or booking actions. Links and source references remain readable; booking controls are disabled.