@rtrvr-ai/rover 4.1.0 → 4.2.1

package/README.md

@@ -514,10 +514,17 @@ const RoverWidget = dynamic(() => import('./RoverWidget'), { ssr: false });
 | `ui.thoughtStyle` | `'concise_cards' \| 'minimal'` | `'concise_cards'` | Thought rendering style |
 | `ui.panel.resizable` | `boolean` | `true` | Enables desktop freeform resizing plus phone/tablet snap-height resizing with per-device memory |
 | `ui.showTaskControls` | `boolean` | `true` | Show new/end task controls |
-| `ui.shortcuts` | `RoverShortcut[]` | `[]` | Suggested journeys (max 100 stored, max 12 rendered by default; lower site-key policy caps are enforced). Shortcuts can also publish agent-facing metadata such as `tags`, `examples`, `inputSchema`, `outputSchema`, `sideEffect`, and `requiresConfirmation`. |
+| `ui.shortcuts` | `RoverShortcut[]` | `[]` | Suggested journeys (max 100 stored, max 12 rendered by default; lower site-key policy caps are enforced). Set `runKind: 'guide'` for onboarding/demo journeys that should narrate under the guided default. Shortcuts can also publish agent-facing metadata such as `tags`, `examples`, `inputSchema`, `outputSchema`, `sideEffect`, and `requiresConfirmation`. |
 | `cloudSandboxEnabled` | `boolean` | `false` | Owner-facing shorthand for cloud execution plus approved third-party browsing. When `true`, Rover materializes `tools.web.enableExternalWebContext=true` and `tools.web.scrapeMode='on_demand'`. |
 | `ui.greeting` | `{ text?, delay?, duration?, disabled? }` | — | Greeting bubble config (`{name}` token supported) |
 | `ui.voice` | `{ enabled?: boolean; language?: string; autoStopMs?: number }` | — | Browser dictation for supported Chromium browsers. Rover fills the draft live, waits for post-speech silence before stopping, and the user still sends manually. |
+| `ui.experience.audio.narration.enabled` | `boolean` | `true` | Owner gate for Web Speech step narration. Visitors get a site-scoped speaker toggle when supported. |
+| `ui.experience.audio.narration.defaultMode` | `'guided' \| 'always' \| 'off'` | `'guided'` | Speak guided/demo runs by default, every run, or stay off unless the visitor enables it. |
+| `ui.experience.audio.narration.rate` | `number` | `1` | Web Speech playback rate, clamped to `0.85`-`1.15`. |
+| `ui.experience.audio.narration.language` | `string` | `'en-US'` | Preferred narration language for voice matching. |
+| `ui.experience.audio.narration.voicePreference` | `'auto' \| 'system' \| 'natural'` | `'auto'` | Voice matching preference; `natural` prefers higher-quality browser voices when available. |
+| `ui.experience.motion.actionSpotlight` | `boolean` | `true` | Highlights the element Rover is clicking, typing into, selecting, or scrolling to. |
+| `ui.experience.motion.actionSpotlightColor` | `"#RRGGBB"` | `"#FF4C00"` | Ring and glow color for Action Spotlight. |
 
 ### Web Tools
 
@@ -530,7 +537,7 @@ const RoverWidget = dynamic(() => import('./RoverWidget'), { ssr: false });
 | `tools.web.denyDomains` | `string[]` | `[]` | External context denylist |
 | `tools.client` | `ClientToolDefinition[]` | `[]` | Runtime-registered client tools. Tool definitions can include `title`, `outputSchema`, and `annotations` (`whenToUse`, `whyUse`, `examples`, `sideEffect`, `requiresConfirmation`) to improve model tool selection and discovery-card quality. |
 | `agentDiscovery` | `{ enabled?, siteName?, description?, version?, siteUrl?, agentCardUrl?, roverSiteUrl?, llmsUrl?, hostSurfaceSelector?, preferExecution?, discoverySurface?, additionalSkills? }` | — | Optional overrides for Rover's generated discovery surfaces. `rover-site.json` is the authoritative rich profile, `agent-card.json` is the interop card, and `discoverySurface.beaconLabel` now feeds the visible seed/presence CTA text in production. Legacy `visibleCue` / `visibleCueLabel` remain compatibility inputs only. |
-| `pageConfig` | `RoverPageCaptureConfig` | — | Optional per-site page-capture overrides such as `disableAutoScroll`, settle timing, and sparse-tree retry settings |
+| `pageConfig` | `RoverPageCaptureConfig` | `{ disableAutoScroll: true }` for generated installs | Optional per-site page-capture overrides such as `disableAutoScroll`, settle timing, and sparse-tree retry settings. Set `disableAutoScroll: false` only when automatic page-capture scrolling is desired. |
 
 ### AI-Callable URLs (Deep Links)
 
@@ -588,13 +595,13 @@ Content-Type: application/json
 
 {
   "url": "https://www.rtrvr.ai",
-  "goal": "Get me the latest blog post",
+  "prompt": "Get me the latest blog post",
   "capabilityId": "latest_blog_post",
   "accept": { "modes": ["text", "json"] }
 }
 ```
 
-Use the explicit A2W run envelope with `goal` for natural-language instructions and `shortcut` for saved journeys.
+Use the explicit A2W run envelope with `prompt` for natural-language instructions and `shortcutId` for saved journeys. `goal` is still accepted as a compatibility alias.
 
 Callers may also provide structured visiting-agent metadata:
 
@@ -604,7 +611,7 @@ Content-Type: application/json
 
 {
   "url": "https://www.rtrvr.ai",
-  "goal": "Get me the latest blog post",
+  "prompt": "Get me the latest blog post",
   "agent": {
     "key": "gpt-5.4-demo-agent",
     "name": "GPT-5.4 Demo Agent",
@@ -627,6 +634,8 @@ The returned run URL is the canonical resource:
 - `DELETE` to cancel
 - a `workflow` URL when the run belongs to an aggregated multi-site workflow
 
+Run creation may return `202 Accepted` before work is complete. The payload includes `links.poll`, `links.stream`, `links.ndjson`, `terminalStatuses`, `interactiveStatuses`, and `retryAfterMs` so outside agents can keep following the run without guessing.
+
 Run creation may also return browser handoff URLs:
 
 - `open`: clean receipt URL for browser attach
@@ -635,7 +644,7 @@ Run creation may also return browser handoff URLs:
 The run URL remains canonical; receipt links are only a browser handoff layer over that same run.
 
 - `Prefer: execution=browser` keeps execution browser-first
-- `Prefer: execution=cloud` is the explicit browserless path today
+- `Prefer: execution=cloud, wait=10` is the explicit browserless path for callers that want a short initial wait before following the returned links
 - `Prefer: execution=auto` prefers browser attach first; delayed cloud auto-promotion is a follow-up robustness phase
 
 Rover deep links like `?rover=` and `?rover_shortcut=` remain the simple browser-first entrypoints; `/v1/a2w/runs` is the machine-oriented protocol. Cross-site workflows and handoffs extend that same public contract rather than replacing it.
@@ -645,12 +654,13 @@ Rover deep links like `?rover=` and `?rover_shortcut=` remain the simple browser
 Rover normalizes visiting-agent attribution in this order:
 
 1. verified signed signal
-2. explicit `agent` object on A2W run creation or handoffs
-3. heuristic headers such as `User-Agent`, `Signature-Agent`, `Signature`, `Signature-Input`, and `X-RTRVR-Client-Id`
-4. advanced local fallbacks such as RoverBook `identityResolver`
-5. anonymous fallback
+2. Signature-Agent directory/signature-envelope evidence without full request verification
+3. explicit `agent` object on A2W run creation or handoffs
+4. heuristic headers such as `User-Agent`, `Signature-Agent`, `Signature`, `Signature-Input`, and `X-RTRVR-Client-Id`
+5. advanced local fallbacks such as RoverBook `identityResolver`
+6. anonymous fallback
 
-Trust tiers are `verified_signed`, `signed_directory_only`, `self_reported`, `heuristic`, and `anonymous`. Unsigned headers never escalate above `heuristic`.
+Trust tiers are `verified_signed`, `signed_directory_only`, `self_reported`, `heuristic`, and `anonymous`. The stored `agentKey` is chosen from explicit agent key fields first, then `clientId`, then `Signature-Agent`, then previous attribution. `signed_directory_only` means the chosen identity had Signature-Agent directory/signature-envelope evidence, but no completed HTTP Message Signature verification. Loose headers without that evidence remain `heuristic`.
 
 ### Cross-site workflows and handoffs
 

package/dist/agentDiscovery.d.ts

@@ -63,6 +63,7 @@ export type RoverPublicSkillDefinition = {
         shortcutId?: string;
         prompt?: string;
         routing?: 'auto' | 'act' | 'planner';
+        runKind?: 'guide' | 'task';
         toolName?: string;
         run?: {
             endpoint: string;

package/dist/agentDiscovery.js

@@ -414,7 +414,7 @@ function normalizeAnnotations(value) {
         requiresConfirmation: typeof annotations.requiresConfirmation === 'boolean'
             ? annotations.requiresConfirmation
             : undefined,
-        preferredInterface: annotations.preferredInterface === 'task'
+        preferredInterface: annotations.preferredInterface === 'run'
             || annotations.preferredInterface === 'shortcut'
             || annotations.preferredInterface === 'client_tool'
             || annotations.preferredInterface === 'webmcp'
@@ -472,6 +472,7 @@ function normalizePublishedShortcut(shortcut) {
         prompt,
         ...(description ? { description } : {}),
         ...(shortcut.routing ? { routing: shortcut.routing } : {}),
+        ...(shortcut.runKind === 'guide' || shortcut.runKind === 'task' ? { runKind: shortcut.runKind } : {}),
     };
 }
 function buildShortcutSkill(shortcut, config, runEndpoint) {
@@ -518,12 +519,13 @@ function buildShortcutSkill(shortcut, config, runEndpoint) {
             shortcutId: id,
             prompt,
             routing: shortcut.routing,
+            runKind: shortcut.runKind,
             deepLink: buildDeepLink(config.siteUrl, id),
             run: {
                 endpoint: runEndpoint,
                 payload: {
                     url: normalizeSiteUrl(config.siteUrl),
-                    shortcut: id,
+                    shortcutId: id,
                 },
                 preferExecution: config.preferExecution || 'auto',
             },
@@ -879,6 +881,7 @@ export function createRoverAgentCard(config) {
                 instructions: [
                     'Prefer exact Rover shortcuts and explicit site tools over raw DOM automation when the user goal matches a published skill.',
                     'Use POST /v1/a2w/runs when you need structured A2W progress, continuation input, or a stable final result channel.',
+                    'For browserless calls, send Prefer: execution=cloud, wait=10 and follow links.stream, links.ndjson, or links.poll until terminal or input_required.',
                     'Fall back to generic DOM automation only when no matching Rover shortcut or explicit tool exists for the requested outcome.',
                 ],
                 capabilitiesGraph: capabilityGraph.capabilities,
@@ -1025,15 +1028,15 @@ export function createRoverAgentDiscoveryTags(config) {
     const escapedRoverSiteJson = escapeScriptJson(roverSiteJson);
     const escapedPageManifestJson = escapeScriptJson(pageManifestJson);
     const lines = [
-        `<script type="application/agent+json">${markerJson}</script>`,
-        `<link rel="service-desc" href="${escapeHtmlAttr(serviceDescHref)}" type="application/json" />`,
+        `<script type="application/agent+json" data-rover-agent-discovery="marker">${markerJson}</script>`,
+        `<link rel="service-desc" href="${escapeHtmlAttr(serviceDescHref)}" type="application/json" data-rover-agent-discovery="service-desc" />`,
     ];
     if (llmsUrl) {
-        lines.push(`<link rel="service-doc" href="${escapeHtmlAttr(llmsUrl)}" type="text/markdown" />`);
+        lines.push(`<link rel="service-doc" href="${escapeHtmlAttr(llmsUrl)}" type="text/markdown" data-rover-agent-discovery="service-doc" />`);
     }
-    lines.push(`<script type="application/rover-site+json">${escapedRoverSiteJson}</script>`);
-    lines.push(`<script type="application/rover-page+json">${escapedPageManifestJson}</script>`);
-    lines.push(`<script type="application/agent-card+json">${escapedCardJson}</script>`);
+    lines.push(`<script type="application/rover-site+json" data-rover-agent-discovery="rover-site">${escapedRoverSiteJson}</script>`);
+    lines.push(`<script type="application/rover-page+json" data-rover-agent-discovery="page">${escapedPageManifestJson}</script>`);
+    lines.push(`<script type="application/agent-card+json" data-rover-agent-discovery="agent-card">${escapedCardJson}</script>`);
     return lines.join('\n');
 }
 export { createRoverAgentDiscoverySnapshot };