@rtrvr-ai/rover 3.0.0 → 4.0.0

package/README.md

@@ -13,6 +13,8 @@ Embed on websites, browser extensions, Electron apps, or any DOM environment.
 
 You need an rtrvr.ai account with available credits. Free accounts get 250 credits/month. [Sign up or manage your plan](https://www.rtrvr.ai/cloud?view=pricing).
 
+Before you test Rover on arbitrary websites, get your site config from Workspace first. Hosted Preview is the only path that does not require Workspace config.
+
 ## Quick Start (Script Tag)
 
 Add this snippet before `</body>` on any page:
@@ -59,6 +61,7 @@ Or use the single-tag shorthand with data attributes:
 <script src="https://rover.rtrvr.ai/embed.js"
   data-site-id="YOUR_SITE_ID"
   data-public-key="pk_site_YOUR_PUBLIC_KEY"
+  data-session-token="rvrsess_YOUR_SHORT_LIVED_SESSION_TOKEN"
   data-allowed-domains="yourdomain.com"
   data-domain-scope-mode="registrable_domain">
 </script>
@@ -66,12 +69,276 @@ Or use the single-tag shorthand with data attributes:
 
 Use `data-domain-scope-mode="host_only"` to require exact host matches. Plain entries such as `example.com` become exact-host rules in `host_only` mode. In the default `registrable_domain` mode, plain entries match the apex host and its subdomains, while `*.example.com` matches subdomains only.
 
+For temporary preview sessions, `data-session-token` can bootstrap Rover without a `publicKey`. If you also have a `sessionId`, add `data-session-id` for a stable runtime boundary.
+
 Common patterns:
 
 - `allowedDomains: ['example.com']` with `registrable_domain` allows `example.com` and all subdomains.
 - `allowedDomains: ['*.example.com']` allows subdomains only, not the apex host.
 - `allowedDomains: ['app.example.com']` with `registrable_domain` allows `app.example.com` and its subdomains, but not sibling hosts.
-- `allowedDomains: ['example.com']` with `host_only` allows only the exact host `example.com`.
+- `allowedDomains: ['example.com']` with `host_only` allows only the exact host `example.com`; sibling subdomains are blocked unless you explicitly list them.
+
+## Preview Helpers
+
+The SDK also exports generic helper utilities for live demos and previews:
+
+```ts
+import {
+  attachLaunch,
+  createRoverAgentCardJson,
+  createRoverAgentDiscoveryTags,
+  createRoverBookmarklet,
+  createRoverConsoleSnippet,
+  createRoverOwnerInstallBundle,
+  createRoverServiceDescLinkHeader,
+  createRoverScriptTagSnippet,
+} from '@rtrvr-ai/rover';
+```
+
+Use `createRoverConsoleSnippet(...)` and `createRoverBookmarklet(...)` to generate one-click bootstrap payloads, and `attachLaunch(...)` when you want to attach a pre-created launch from code.
+
+Before you use any of these helpers on another website:
+
+1. Open Rover Workspace.
+2. Create or rotate a site key so Workspace reveals the full `pk_site_*` value.
+3. Copy the **test config JSON** from Workspace.
+4. Either paste that JSON into the Rover website's "Try on Other Sites" tool, or pass the same values into the SDK helpers below.
+
+### Which helper to use
+
+| Path | What you need | Best for | Persistence |
+|---|---|---|---|
+| Hosted Preview | Signed-in URL + prompt | Rover-managed demos | Temporary preview session |
+| Preview Helper | Workspace test config JSON or hosted handoff | Multi-page desktop demos | Re-injects after reload/navigation |
+| Console | Workspace test config JSON + generated snippet | Fast DevTools demos | Current page only |
+| Bookmarklet | Workspace test config JSON + generated bookmarklet | Drag-and-click demos | Current page only |
+| Production install | Workspace install snippet | Real site install | Persistent |
+
+- `createRoverConsoleSnippet(...)`
+  Best for desktop demos, debugging, and screen-sharing when you can paste into DevTools.
+- `createRoverBookmarklet(...)`
+  Best for quick one-click demos across many pages, with the same current-page limitations as manual injection.
+- `createRoverScriptTagSnippet(...)`
+  Best for generating an actual snippet from known config values such as Workspace `siteId` and `publicKey`.
+- `createRoverOwnerInstallBundle(...)`
+  Best for canonical owner-facing install output when you need a body-safe runtime snippet plus separate head discovery HTML, `rover-site.json`, `agent-card.json`, and optional `llms.txt`.
+- `createRoverAgentCardJson(...)`, `createRoverAgentDiscoveryTags(...)`, `createRoverServiceDescLinkHeader(...)`
+  Best for publishing source-visible discovery metadata so arbitrary agents can find Rover skills before falling back to DOM automation.
+- `attachLaunch(...)`
+  Best when you already created a launch elsewhere and want Rover to attach to it after boot.
+
+### Example: console snippet from Workspace config
+
+```ts
+import { createRoverConsoleSnippet } from '@rtrvr-ai/rover';
+
+const snippet = createRoverConsoleSnippet({
+  siteId: 'site_123',
+  publicKey: 'pk_site_123',
+  siteKeyId: 'key_123',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'registrable_domain',
+  apiBase: 'https://agent.rtrvr.ai',
+  openOnInit: true,
+  mode: 'full',
+  allowActions: true,
+});
+```
+
+### Example: bookmarklet from Workspace config
+
+```ts
+import { createRoverBookmarklet } from '@rtrvr-ai/rover';
+
+const bookmarklet = createRoverBookmarklet({
+  siteId: 'site_123',
+  publicKey: 'pk_site_123',
+  siteKeyId: 'key_123',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'registrable_domain',
+  apiBase: 'https://agent.rtrvr.ai',
+});
+```
+
+### Example: production script-tag snippet from Workspace config
+
+```ts
+import { createRoverScriptTagSnippet } from '@rtrvr-ai/rover';
+
+const snippet = createRoverScriptTagSnippet({
+  siteId: 'site_123',
+  publicKey: 'pk_site_123',
+  siteKeyId: 'key_123',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'registrable_domain',
+  apiBase: 'https://agent.rtrvr.ai',
+});
+```
+
+### Example: canonical owner install bundle
+
+```ts
+import { createRoverOwnerInstallBundle } from '@rtrvr-ai/rover';
+
+const bundle = createRoverOwnerInstallBundle({
+  bootConfig: {
+    siteId: 'site_123',
+    publicKey: 'pk_site_123',
+    siteKeyId: 'key_123',
+    allowedDomains: ['example.com'],
+    domainScopeMode: 'registrable_domain',
+  },
+  discovery: {
+    siteId: 'site_123',
+    siteUrl: 'https://example.com/',
+    siteName: 'Example Store',
+    roverSiteUrl: '/.well-known/rover-site.json',
+    agentCardUrl: '/.well-known/agent-card.json',
+    llmsUrl: '/llms.txt',
+  },
+  emitLlmsTxt: true,
+});
+
+bundle.bodyInstallHtml;     // paste before </body>
+bundle.headDiscoveryHtml;   // place in <head> or managed head custom code
+bundle.roverSiteJson;       // publish at /.well-known/rover-site.json
+bundle.agentCardJson;       // publish at /.well-known/agent-card.json
+bundle.serviceDescLinkHeader;
+bundle.llmsTxt;
+```
+
+### Example: attach a pre-created launch
+
+```ts
+import { attachLaunch, boot } from '@rtrvr-ai/rover';
+
+boot({
+  siteId: 'preview_site',
+  sessionToken: 'rvrsess_short_lived_token',
+  allowedDomains: ['example.com'],
+  domainScopeMode: 'host_only',
+});
+
+attachLaunch({
+  requestId: 'rl_123',
+  attachToken: 'attach_123',
+});
+```
+
+### Two config sources
+
+Use one of these sources for the helper functions above:
+
+- **Workspace production config**
+  Persistent `siteId`, `publicKey`, optional `siteKeyId`, `allowedDomains`, and `domainScopeMode` from Rover Workspace.
+- **Hosted preview config**
+  Short-lived preview/runtime values produced by Rover Instant Preview on the website or by your own preview service.
+
+Get Workspace config from:
+
+- [https://www.rtrvr.ai/rover/workspace](https://www.rtrvr.ai/rover/workspace)
+- [https://rover.rtrvr.ai/workspace](https://rover.rtrvr.ai/workspace)
+
+If you want the exact human walkthrough instead of jumping straight into code:
+
+- website guide: [https://www.rtrvr.ai/rover/docs/try-on-other-sites](https://www.rtrvr.ai/rover/docs/try-on-other-sites)
+- repo guide: [../../docs/TRY_ON_OTHER_SITES.md](../../docs/TRY_ON_OTHER_SITES.md)
+- one-click helper path: use the website tool's `Open target with helper` action after pasting the Workspace config
+
+If you want a public extension that can use either config source, see the Preview Helper app:
+
+- [https://github.com/rtrvr-ai/rover/tree/main/apps/preview-helper](https://github.com/rtrvr-ai/rover/tree/main/apps/preview-helper)
+- [https://www.rtrvr.ai/rover/docs/instant-preview-api](https://www.rtrvr.ai/rover/docs/instant-preview-api)
+
+### Agent Discovery Publishing
+
+Use the new discovery helpers when you want generic agents to see explicit Rover skills before they start clicking through the DOM:
+
+```ts
+import {
+  createRoverAgentCardJson,
+  createRoverAgentDiscoveryTags,
+  createRoverServiceDescLinkHeader,
+} from '@rtrvr-ai/rover';
+
+const agentCardJson = createRoverAgentCardJson({
+  siteUrl: 'https://example.com/',
+  siteName: 'Example Store',
+  shortcuts: [
+    {
+      id: 'start_checkout',
+      label: 'Start Checkout',
+      prompt: 'start checkout',
+      description: 'Launch the checkout flow directly.',
+      tags: ['checkout', 'commerce'],
+      examples: ['Start checkout for the current cart.'],
+      sideEffect: 'transactional',
+      requiresConfirmation: true,
+    },
+  ],
+});
+
+const discoveryTags = createRoverAgentDiscoveryTags({
+  siteUrl: 'https://example.com/',
+  siteName: 'Example Store',
+});
+
+const linkHeader = createRoverServiceDescLinkHeader({
+  agentCardUrl: '/.well-known/agent-card.json',
+  llmsUrl: '/llms.txt',
+});
+```
+
+Recommended rollout:
+
+1. Serve `roverSiteJson` at `/.well-known/rover-site.json`.
+2. Serve `agentCardJson` at `/.well-known/agent-card.json`.
+3. Add `discoveryTags` near the Rover snippet in page source.
+4. Add the `Link` header generated by `createRoverServiceDescLinkHeader(...)`.
+
+### Hosted preview handoff behavior
+
+The open-source helper extension understands hosted preview handoff URLs that include:
+
+- `rover_preview_id`
+- `rover_preview_token`
+- `rover_preview_api`
+
+When those are present, the helper can fetch the short-lived preview config from the hosted Rover API and reconnect it across navigation.
+
+### Security notes
+
+- `pk_site_*` values are Workspace install credentials for a real site.
+- `rvrsess_*` values are short-lived runtime session credentials.
+- Preview tokens are demo credentials and should be treated as ephemeral.
+- Do not treat preview tokens as a replacement for production Workspace site keys.
+- Keep preview or helper injections scoped to the intended host with `allowedDomains` and the right `domainScopeMode`.
+- Generic `publicKey` config is the normal Workspace path. `sessionToken` is the temporary preview/runtime path.
+
+### Troubleshooting
+
+- **`This API key is missing capability: roverEmbed`**
+  Your Workspace key is not embed-enabled. Rotate or create an embed-ready key, then rebuild the snippet or bookmarklet from the fresh test config JSON.
+- **`React has blocked a javascript: URL`**
+  Delete any old Rover bookmarklet and recreate it from the latest Rover Live Test page. The bookmarklet must be dragged from Rover's dedicated drag control, not clicked on the Rover page itself.
+- **Console or Bookmarklet worked once, then stopped**
+  Those are current-page-only methods. A full reload drops the injected JavaScript.
+- **A site still blocks Rover after you generated valid output**
+  Some sites enforce strict CSP or reload aggressively. Use the Preview Helper or Hosted Preview instead.
+- **`Open hosted shell` does nothing**
+  Hosted Preview should open Rover's dedicated hosted viewer route, not the launcher page.
+
+### Hosted playground
+
+If you want the full managed preview flow, including preview creation and Workspace handoff, use the hosted website:
+
+- [https://www.rtrvr.ai/rover/instant-preview](https://www.rtrvr.ai/rover/instant-preview)
+
+More architecture detail:
+
+- [Instant Preview architecture](https://github.com/rtrvr-ai/rover/blob/main/docs/INSTANT_PREVIEW.md)
+- [Hosted preview API docs](https://www.rtrvr.ai/rover/docs/instant-preview-api)
+- [Hosted preview OpenAPI spec](https://raw.githubusercontent.com/rtrvr-ai/rtrvr-cloud-backend/main/docs/rover-instant-preview.openapi.yaml)
 
 ## npm Install
 
@@ -146,7 +413,7 @@ const RoverWidget = dynamic(() => import('./RoverWidget'), { ssr: false });
 | `visitor` | `{ name?: string; email?: string }` | — | Optional visitor profile for greeting personalization. Recommended flow is async updates via `identify(...)` after login/user hydration. |
 | `apiBase` | `string` | `https://agent.rtrvr.ai` | Optional API base override. Rover uses `/v2/rover/*` under this base. |
 | `allowedDomains` | `string[]` | `[]` | Hostnames or patterns where Rover may operate. In `registrable_domain`, plain `example.com` covers the apex host and subdomains. |
-| `domainScopeMode` | `'registrable_domain' \| 'host_only'` | `'registrable_domain'` | How Rover interprets plain `allowedDomains` entries: `registrable_domain` = apex + subdomains, `host_only` = exact host only. |
+| `domainScopeMode` | `'registrable_domain' \| 'host_only'` | `'registrable_domain'` | How Rover interprets plain `allowedDomains` entries: `registrable_domain` = apex + subdomains, `host_only` = exact host only unless you explicitly allow more hosts. |
 | `externalNavigationPolicy` | `'open_new_tab_notice' \| 'block' \| 'allow'` | `'open_new_tab_notice'` | External navigation policy |
 | `navigation.crossHostPolicy` | `'same_tab' \| 'open_new_tab'` | `'same_tab'` | In-scope cross-host navigation policy |
 | `mode` | `'full' \| 'safe'` | `'full'` | Runtime mode |
@@ -235,11 +502,12 @@ const RoverWidget = dynamic(() => import('./RoverWidget'), { ssr: false });
 | `ui.mascot.disabled` | `boolean` | `false` | Disable mascot video |
 | `ui.mascot.mp4Url` | `string` | default | Custom mascot MP4 URL |
 | `ui.mascot.webmUrl` | `string` | default | Custom mascot WebM URL |
-| `ui.muted` | `boolean` | `true` | Start with audio muted on first load; stored browser preference wins after the user toggles sound |
+| `ui.mascot.soundEnabled` | `boolean` | `false` | Owner gate for mascot sound. Rover keeps mascot audio unavailable unless this is explicitly `true`. |
+| `ui.muted` | `boolean` | `true` | Initial mute state only when mascot sound is enabled. Visitor preference is stored per Rover site after they toggle sound. |
 | `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) |
+| `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.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. |
 
@@ -252,7 +520,8 @@ const RoverWidget = dynamic(() => import('./RoverWidget'), { ssr: false });
 | `tools.web.scrapeMode` | `'off' \| 'on_demand'` | `'off'` | On-demand external tab scrape mode |
 | `tools.web.allowDomains` | `string[]` | `[]` | External context allowlist |
 | `tools.web.denyDomains` | `string[]` | `[]` | External context denylist |
-| `tools.client` | `ClientToolDefinition[]` | `[]` | Runtime-registered client tools |
+| `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 |
 
 ### AI-Callable URLs (Deep Links)
@@ -261,7 +530,7 @@ Rover can be triggered via URL query parameters, turning any page into an AI-cal
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `deepLink.enabled` | `boolean` | `false` | Enable URL-triggered Rover |
+| `deepLink.enabled` | `boolean` | derived from `siteConfig.aiAccess.enabled` when available, otherwise `false` | Advanced manual override for URL-triggered Rover |
 | `deepLink.promptParam` | `string` | `'rover'` | Query parameter for natural-language prompts |
 | `deepLink.shortcutParam` | `string` | `'rover_shortcut'` | Query parameter for shortcut IDs |
 | `deepLink.consume` | `boolean` | `true` | Strip deep link params from URL after reading |
@@ -280,9 +549,9 @@ https://example.com?rover_shortcut=checkout_flow
 
 For AI or CLI-triggered entrypoints, prefer exact shortcut IDs for repeatable flows.
 
-When a site key or session token is used, Rover fetches cloud site config via `/v2/rover/session/open` (shortcuts + greeting + voice + pageConfig).
+When a site key or session token is used, Rover fetches cloud site config via `/v2/rover/session/open` (shortcuts + `businessType` + sparse `experience` overrides + legacy voice compatibility + `aiAccess` + `pageConfig`).
 If the same field exists in both cloud config and boot config, boot config wins.
-`deepLink` is boot/runtime only and is not persisted in cloud site config.
+`siteConfig.aiAccess.enabled` is the canonical owner-facing launch switch persisted from Workspace/Webflow. `deepLink` stays boot/runtime only for advanced manual overrides such as custom param names, explicit enable/disable, or disabling URL param consumption.
 
 If you enable `tools.web.scrapeMode: 'on_demand'`, use a site key capability profile that includes cloud scrape support.
 
@@ -303,13 +572,22 @@ The source-visible marker is optional but recommended:
 <script type="application/agent+json">{"task":"https://agent.rtrvr.ai/v1/tasks"}</script>
 ```
 
+For stronger pre-task discovery, publish `/.well-known/rover-site.json` as Rover's authoritative rich profile, publish `/.well-known/agent-card.json` as the interop card, add a `Link: </.well-known/agent-card.json>; rel="service-desc"` header, and include inline discovery tags generated by `createRoverAgentDiscoveryTags(...)`.
+
 ```http
 POST https://agent.rtrvr.ai/v1/tasks
 Content-Type: application/json
 
-{ "url": "https://www.rtrvr.ai", "prompt": "get me the latest blog post" }
+{
+  "url": "https://www.rtrvr.ai",
+  "goal": "Get me the latest blog post",
+  "capabilityId": "latest_blog_post",
+  "accept": { "modes": ["text", "json"] }
+}
 ```
 
+Compatibility aliases such as `{ "url": "...", "prompt": "..." }` and `{ "url": "...", "shortcutId": "..." }` still work, but the richer task envelope is the canonical contract.
+
 Callers may also provide structured visiting-agent metadata:
 
 ```http
@@ -318,7 +596,7 @@ Content-Type: application/json
 
 {
   "url": "https://www.rtrvr.ai",
-  "prompt": "get me the latest blog post",
+  "goal": "Get me the latest blog post",
   "agent": {
     "key": "gpt-5.4-demo-agent",
     "name": "GPT-5.4 Demo Agent",
@@ -358,13 +636,13 @@ Rover deep links like `?rover=` and `?rover_shortcut=` remain the simple browser
 
 Rover normalizes visiting-agent attribution in this order:
 
-1. verified signal
+1. verified signed signal
 2. explicit `agent` object on public task 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
 
-Current launch behavior emits `self_reported`, `heuristic`, and `anonymous`. `verified` remains reserved for a real verifier and is not inferred from plain headers alone.
+Trust tiers are `verified_signed`, `signed_directory_only`, `self_reported`, `heuristic`, and `anonymous`. Unsigned headers never escalate above `heuristic`.
 
 ### Cross-site workflows and handoffs
 
@@ -439,6 +717,7 @@ rover.send('Hello');
 | `newTask(options?)` | Start a new task, clearing context |
 | `endTask(options?)` | End the current task |
 | `getState()` | Get current runtime state |
+| `getAgentCard()` | Build the current Rover capability card from live shortcuts, client tools, and WebMCP metadata |
 | `update(config)` | Update configuration without rebooting |
 | `registerTool(def, handler)` | Register a client-side tool |
 | `requestSigned(url, init?)` | Issue a fetch signed with the current Rover session token and site/session headers |