@rtrvr-ai/rover 2.3.0 → 3.0.1

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:
@@ -37,6 +39,13 @@ Add this snippet before `</body>` on any page:
 <script src="https://rover.rtrvr.ai/embed.js" async></script>
 ```
 
+If RoverBook is enabled for the site in Rover Workspace, the generated install snippet also includes `https://rover.rtrvr.ai/roverbook.js` plus an inline attach block that calls `window.RoverBook.enableRoverBook(window.rover, ...)`. Copy the Workspace snippet as-is for production installs.
+
+Workspace also controls site mode:
+
+- `Full Rover agent`: action-capable Rover runtime
+- `RoverBook analytics-only`: embed-oriented RoverBook deployment with action tools disabled
+
 Get `siteId`, `publicKey` (`pk_site_*`), and optional `siteKeyId` from Rover Workspace:
 
 - `https://rover.rtrvr.ai/workspace`
@@ -52,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>
@@ -59,6 +69,8 @@ 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.
@@ -66,6 +78,182 @@ Common patterns:
 - `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`.
 
+## Preview Helpers
+
+The SDK also exports generic helper utilities for live demos and previews:
+
+```ts
+import {
+  attachLaunch,
+  createRoverBookmarklet,
+  createRoverConsoleSnippet,
+  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`.
+- `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: 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)
+
+### 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
 
 ```bash
@@ -303,6 +491,26 @@ Content-Type: application/json
 { "url": "https://www.rtrvr.ai", "prompt": "get me the latest blog post" }
 ```
 
+Callers may also provide structured visiting-agent metadata:
+
+```http
+POST https://agent.rtrvr.ai/v1/tasks
+Content-Type: application/json
+
+{
+  "url": "https://www.rtrvr.ai",
+  "prompt": "get me the latest blog post",
+  "agent": {
+    "key": "gpt-5.4-demo-agent",
+    "name": "GPT-5.4 Demo Agent",
+    "vendor": "OpenAI",
+    "model": "gpt-5.4",
+    "version": "2026-03",
+    "homepage": "https://openai.com"
+  }
+}
+```
+
 Anonymous AI callers do **not** need `siteId`, `publicKey`, or `siteKeyId`.
 
 The returned task URL is the canonical resource:
@@ -327,6 +535,18 @@ The task URL remains canonical; receipt links are only a browser handoff layer o
 
 Rover deep links like `?rover=` and `?rover_shortcut=` remain the simple browser-first entrypoints; `/v1/tasks` is the machine-oriented protocol. Cross-site workflows and handoffs extend that same public contract rather than replacing it.
 
+### Agent identity attribution
+
+Rover normalizes visiting-agent attribution in this order:
+
+1. verified 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.
+
 ### Cross-site workflows and handoffs
 
 Public tasks can delegate to Rover on another Rover-enabled site without leaving the same protocol surface.
@@ -335,6 +555,8 @@ Public tasks can delegate to Rover on another Rover-enabled site without leaving
 - `GET /v1/workflows/{id}` returns aggregated workflow state or stream
 - child tasks inherit the same workflow lineage as the parent
 
+Handoff creation also accepts the optional `agent` object so a child task can inherit or explicitly override visiting-agent attribution.
+
 Receiving sites must explicitly opt in through Workspace/site config:
 
 - `aiAccess.enabled = true`
@@ -400,6 +622,8 @@ rover.send('Hello');
 | `getState()` | Get current runtime state |
 | `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 |
+| `registerPromptContextProvider(provider)` | Inject bounded prompt context before a fresh Rover task/run |
 | `identify(visitor)` | Update visitor profile after boot (for async login/user hydration) |
 | `on(event, handler)` | Subscribe to events (returns unsubscribe fn) |
 
@@ -423,12 +647,17 @@ rover.on('error', (err) => console.error(err));
 | `navigation_guardrail` | `{ url, policy }` | Out-of-scope navigation intercepted |
 | `task_started` | `{ reason }` | New task started |
 | `task_ended` | `{ reason }` | Task ended |
+| `run_started` | `{ taskId, runId, taskBoundaryId, state, taskComplete, needsUserInput, summary? }` | Public run lifecycle start event |
+| `run_state_transition` | `{ taskId, runId, taskBoundaryId, state, taskComplete, needsUserInput, summary?, error? }` | Public run lifecycle transition |
+| `run_completed` | `{ taskId, runId, taskBoundaryId, state, taskComplete, needsUserInput, summary?, error? }` | Terminal public run lifecycle event |
 | `checkpoint_state` | `{ state, reason?, action?, code?, message? }` | Checkpoint sync state updates |
 | `checkpoint_error` | `{ action, code?, message, ... }` | Checkpoint request failure details |
 | `tab_event_conflict_retry` | `{ runId, conflict?, ... }` | One stale seq/epoch tab-event conflict was recovered by silent retry |
 | `tab_event_conflict_exhausted` | `{ runId, conflict?, ... }` | Tab-event stale conflict retry exhausted (non-fatal; projection sync follows) |
 | `checkpoint_token_missing` | `{ action, status }` | Legacy checkpoint browser path blocked |
 
+`requestSigned(...)` and `registerPromptContextProvider(...)` are the main extension points RoverBook uses for signed analytics writes and memory injection.
+
 ## Content Security Policy (CSP)
 
 If your site sets a CSP header, add these directives: