@tempoxyz/mercator 0.0.608 → 0.0.613

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -30,20 +30,22 @@ nix run github:tempoxyz/mercator -- setup
30
30
 
31
31
  Install it into your Nix profile with `nix profile install github:tempoxyz/mercator`.
32
32
 
33
- Setup detects supported client CLIs and desktop configuration footprints, installs the Mercator MCP
34
- integration and one local Codex/ChatGPT plugin, then tries the public `tempoxyz/docs` plugin
35
- marketplace for Claude Code and Grok CLI,
36
- and verifies the protected endpoint. The default route is `/mcp/auth`. Native OAuth clients open
37
- Account on first use; Grok setup opens Tempo Wallet immediately and stores its bounded bearer in
38
- Grok's user MCP configuration. Existing Mercator registrations using `/mcp` are upgraded
39
- automatically; unrelated custom endpoints are preserved. No wallet key or API key is printed or
40
- copied. In an interactive terminal, every detected client starts checked and can be toggled before
41
- setup continues. Detection and selection show the human client name and whether setup installs MCP
42
- alone or a plugin plus MCP. The final summary distinguishes installed, already configured, skipped,
43
- and failed work, preserves successful integrations when another target fails, and ends with three
44
- copyable prompts for the first Mercator run. Setup reads the current public suggestion catalog and
45
- uses bundled prompts when it is unavailable. The desktop plugin includes a focused Mercator skill by
46
- default. Pass setup options through the bootstrap command after `sh -s --`:
33
+ Setup:
34
+
35
+ - Detects supported client CLIs and desktop configuration.
36
+ - Lets interactive users select from every detected client.
37
+ - Installs the Mercator MCP integration and one local Codex/ChatGPT plugin.
38
+ - Uses the public `tempoxyz/docs` plugin marketplace for Claude Code and Grok CLI.
39
+ - Connects native OAuth clients to `/mcp/auth`; Grok setup completes browser authorization
40
+ immediately and stores its bounded bearer in Grok's user configuration.
41
+ - Upgrades existing Mercator `/mcp` registrations while preserving unrelated custom endpoints.
42
+ - Never prints or copies wallet keys or API keys.
43
+ - Preserves successful integrations when another target fails.
44
+ - Reports installed, current, skipped, and failed work.
45
+ - Ends with three copyable prompts from the public suggestion catalog or bundled fallback prompts.
46
+
47
+ The desktop plugin includes the Mercator skill by default. Pass setup options through the bootstrap
48
+ command after `sh -s --`:
47
49
 
48
50
  ```sh
49
51
  curl -fsSL https://mercator.sh/install.sh | sh -s -- --client codex --no-skill
@@ -35,13 +35,16 @@ fastest way to determine whether Mercator can complete the request.
35
35
  `get_job`
36
36
 
37
37
  If payment capability is uncertain, or `create_job` unexpectedly requests payment, call
38
- `get_connection_status`. `oauthAuthenticated: true` means the current request has a valid hosted
39
- wallet OAuth grant. The response includes its public wallet address, payment-token balances,
40
- access-key expiry and status, grant ceilings, and live remaining limits. A `ready` access key can
41
- make its first payment; use its signed grant ceiling even if its live remaining limit is zero before
42
- activation. Treat `unavailable` reads as unknown, not zero. `oauthAuthenticated: false` means the
43
- client is using the legacy MCP payment-challenge path and has no inspectable hosted account. Never
44
- request or expose credentials.
38
+ `get_connection_status`:
39
+
40
+ - `oauthAuthenticated: true`: the request has a valid hosted wallet OAuth grant. Inspect its public
41
+ wallet address, balances, access-key status and expiry, grant ceilings, and live remaining limits.
42
+ - `ready`: the key can make its first payment. Before activation, use its signed grant ceiling even
43
+ when the live remaining limit is zero.
44
+ - `unavailable`: the chain read is unknown, not zero.
45
+ - `oauthAuthenticated: false`: the client uses the legacy MCP payment-challenge path and has no
46
+ inspectable hosted account.
47
+ - Never request or expose credentials.
45
48
 
46
49
  1. **Search for the outcome.** Give `search_services` the user's complete intended outcome,
47
50
  constraints, and deliverable. Set `resolution` to `live` so Mercator probes candidate availability
@@ -56,24 +59,25 @@ request or expose credentials.
56
59
  and execute only the requested actions. Legacy `mcp_challenge` clients have no hosted grant:
57
60
  get quote approval or use a sufficient explicit budget before paid execution, including REST fallback.
58
61
  5. **Submit once.** Generate one stable 8-200 character idempotency key and call `create_job` with
59
- the unchanged quoted plan and `totalAmount` as `approved_total`. If the refreshed quote differs,
60
- no charge is made: quote again and proceed within the access-key limits and any explicit user
61
- budget. Legacy clients need approval of the new total unless an explicit budget covers it.
62
- In an OAuth-connected host, Mercator charges the bounded wallet capability and returns
63
- the job directly. The agent host receives no wallet private key. Other clients complete payment
64
- challenges through MCP metadata. If MCP submission and one retry both fail, a host that already
65
- has a ready local Mercator wallet may submit the equivalent bounded REST request with the same
66
- plan, idempotency key, and approved total. That separate local wallet needs quote approval or a
67
- sufficient explicit budget; a hosted grant does not authorize it. Never install, create, or connect
68
- a wallet for fallback.
62
+ the unchanged quoted plan and `totalAmount` as `approved_total`.
63
+ - Changed quote: no charge occurs. Quote again and continue only within the access-key limits and
64
+ any explicit user budget. Legacy clients need approval unless that budget covers the new total.
65
+ - Hosted OAuth: Mercator charges the bounded wallet capability and returns the job. The agent host
66
+ receives no wallet private key.
67
+ - Legacy client: complete the payment challenge through MCP metadata.
68
+ - Failed MCP submission and one identical retry: use REST only when the host already has a ready
69
+ local Mercator wallet. Keep the plan, idempotency key, and approved total unchanged. Obtain quote
70
+ approval or stay within an explicit budget; the hosted grant does not authorize the local wallet.
71
+ - Never install, create, or connect a wallet for fallback.
69
72
  6. **Listen for completion.** Persist the returned `jobId` immediately; it is the only status and
70
- resumption capability. Poll `get_job` with bounded backoff. Its default inline mode preserves the
71
- complete cached result. For potentially large jobs, request summary mode and call
72
- `get_job_details` with both `job_id` and `node_id` for each needed ID in `result_node_ids`; use `result_pointer` to retrieve one field
73
- from a large node payload. `ready:false` means the durable job is still
74
- pending or running. `ready:true` is terminal: return either its cached results or stable `error`
75
- to the user. A client timeout or disconnect does not cancel the job. Mercator has no job webhook
76
- or SSE stream, so a status listener must keep polling or resume later with the same job ID.
73
+ resumption capability. Poll `get_job` with bounded backoff.
74
+ - Default inline mode returns the complete cached result.
75
+ - For large jobs, request summary mode. Call `get_job_details` with `job_id` and each needed
76
+ `node_id` from `result_node_ids`; use `result_pointer` for one field from a large node payload.
77
+ - `ready:false`: the job remains pending or running.
78
+ - `ready:true`: return the cached result or stable `error`.
79
+ - A timeout or disconnect does not cancel the job. Mercator has no webhook or SSE stream; keep
80
+ polling or resume later with the same job ID.
77
81
 
78
82
  For a warm Grok Bot installation, target less than two minutes from the user's request to a terminal
79
83
  result. OAuth authorization is a one-time plugin connection, not a per-job wallet setup. Run
@@ -103,19 +107,18 @@ continue automatically through submission and pending status transitions.
103
107
  job remains pending; report the job ID and last status if the caller's wait limit is reached.
104
108
  - Use `create_job_review` only when the user wants to review a completed job. Run its returned
105
109
  zero-spend REST handoff so the original job payer authorizes the review.
106
- - When an unexpected Mercator failure persists after one safe recovery attempt, proactively draft
107
- a bug report for `send_product_feedback`. Also draft for an unexpected terminal job failure:
108
- durable execution has already ended; never submit or pay again just to reproduce it. Return the
109
- failure and any partial results to the user. Follow ordinary validation, funding, authorization,
110
- rate-limit, and empty-search recovery guidance first; those outcomes alone are not product bugs.
111
- - Include the tool name, safe error code, reproduction steps, and expected/actual behavior. Provide
112
- the related Mercator job ID in `job_id` when one exists; omit it if no job was created or its ID
113
- is unknown. Never invent an ID or create a job just to report an issue. The job ID grants result
114
- access and is shared with maintainers for diagnosis. Exclude secrets, credentials, payment
115
- material, personal data, and raw tool inputs or outputs.
116
- Show the draft and ask to send unless the user already authorized reporting this issue. Wallet
117
- authorization is not feedback consent. Send at most once per issue in the conversation, stop
118
- after a decline, and never automatically retry uncertain delivery or report feedback-tool failures.
110
+ - Draft `send_product_feedback` after one safe recovery fails or an unexpected terminal job failure
111
+ occurs. Never submit or pay again merely to reproduce it. Return failures and partial results.
112
+ - Do not treat ordinary validation, funding, authorization, rate-limit, or empty-search outcomes as
113
+ product bugs.
114
+ - Include the tool name, safe error code, reproduction steps, and expected/actual behavior.
115
+ - Include `job_id` only when a related job exists. Never invent one or create a job for reporting.
116
+ The ID grants result access and is shared with maintainers.
117
+ - Exclude secrets, credentials, payment material, personal data, and raw tool inputs or outputs.
118
+ - Show the draft and ask to send unless the user already authorized reporting this issue. Wallet
119
+ authorization is not feedback consent.
120
+ - Send at most once per issue. Stop after a decline. Never retry uncertain delivery automatically or
121
+ report feedback-tool failures.
119
122
 
120
123
  Read [examples](references/examples.md) for compound research, external actions, spending limits,
121
124
  MCP submission, status listening, and recovery patterns.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tempoxyz/mercator",
3
- "version": "0.0.608",
3
+ "version": "0.0.613",
4
4
  "description": "Connect agent clients to the Mercator remote MCP server",
5
5
  "type": "module",
6
6
  "bin": {