@rtrvr-ai/rover 4.2.0 → 4.2.1

package/README.md

@@ -595,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:
 
@@ -611,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",
@@ -634,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
@@ -642,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.
@@ -652,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.js

@@ -525,7 +525,7 @@ function buildShortcutSkill(shortcut, config, runEndpoint) {
                 endpoint: runEndpoint,
                 payload: {
                     url: normalizeSiteUrl(config.siteUrl),
-                    shortcut: id,
+                    shortcutId: id,
                 },
                 preferExecution: config.preferExecution || 'auto',
             },
@@ -881,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,