Tighten agent-facing instructions + verify autonomous flow live

Minimize token cost of the strings an AI agent parses:
- sentinel.ts: runtime `instructions` now leads with protocol: 'v2ray'
  (zero-admin Windows path) and drops the verbose setup() comment; was
  stale (no protocol) and contradicted the Windows-100 docs.
- index.ts /manifest: collapse the V2Ray/zero-prereq explanation that was
  repeated 6x across tldr, platforms, connectWindows.{zeroPrereq,
  wireguardUpgrade,default} and connect.protocolNote into one canonical
  place (connectWindows). Terse pointers elsewhere. ~half the bytes,
  every load-bearing fact preserved.

Autonomous-flow E2E (agent pays node directly in P2P, no operator):
fresh-test/connect-autonomous.mjs + AUTONOMOUS-E2E-RESULTS.txt. Live PASS
on Base/Sentinel: 1 GB per-GB session 45433200, v2ray, US node, exit IP
verified through tunnel, 40.19 P2P spent (~live median). Mnemonic passed
via env, never committed.

Author: Sentinel-Bluebuilder

fresh-test/AUTONOMOUS-E2E-RESULTS.txt

@@ -0,0 +1,57 @@
+x402 AUTONOMOUS-FLOW E2E — LIVE RESULT
+========================================
+Date:        2026-06-14 (UTC)
+Flow:        Autonomous — agent holds its own P2P and pays the node DIRECTLY.
+             No x402 server, no operator, no fee-grant, no MsgShareSubscription.
+Runner:      fresh-test/connect-autonomous.mjs
+SDK:         blue-js-sdk@2.8.0  (blue-js-sdk/ai-path connect())
+Protocol:    v2ray  (zero-admin Windows path)
+Country:     US (SDK auto-picked node)
+
+RESULT: PASS
+------------
+Agent wallet:   sent12r7g5zqj3w6glfqtxztc9qhd82yg4lddvezjt4
+Node selected:  sentnode1qjy6hphezyqzf4l42peut3tgd45c8rpylczs6h
+                "0_Premium_Service_100G_Nibiru129" — Santa Clara, United States
+                v2ray, qualityScore=55
+Session:        45433200  (per-GB, 1 GB)
+Session TX:     9BD199C324800C2C05E6BA46539A9D377AAA0E14BA97D0987DC4DC6D42218AA1
+Handshake:      V2Ray VLESS/TCP/TLS — 104.252.19.187:6699 — connected
+Exit IP:        104.252.19.187  (SDK-verified THROUGH the tunnel)
+Host IP:        67.169.16.153
+Routed:         YES — exit IP differs from host IP
+
+COST
+----
+Before:  1000.00 P2P
+After:    959.81 P2P
+Spent:     40.19 P2P  for a 1 GB per-GB session
+           (right at the live network median of ~40 P2P/GB)
+Gas:       included in the 40.19 (MsgStartSession gas paid by the agent itself)
+
+TIMING
+------
+End-to-end connect:  ~67 s
+  - node discovery (probed 200 US nodes, 197 online): ~46 s
+  - session TX broadcast + index: ~7 s
+  - V2Ray handshake + tunnel verify: ~13 s
+
+NOTES
+-----
+1. The agent paid the node directly. No operator involvement at any step —
+   this is the fully decentralized, self-custody path.
+
+2. V2Ray is a SOCKS-proxy tunnel, NOT a full system TUN route (that's WireGuard).
+   So a top-level fetch() on the host's default route still shows the host IP.
+   The SDK's own through-tunnel IP check (vpn.ip = 104.252.19.187) is the source
+   of truth and confirms traffic exits via the node. For full system routing on
+   Windows, use protocol: 'wireguard' (admin-once) or route the app through the
+   returned SOCKS port.
+
+3. Disconnect was SOFT — session 45433200 is preserved on-chain (status=1) for
+   reuse, so the remaining ~0.96 GB of the 1 GB quota stays available. No
+   MsgCancelSession broadcast. To hard-end and settle the deposit, use
+   disconnectAndEndSession().
+
+4. Zero prerequisites held: admin=true, v2ray binary present. On a non-admin box
+   the v2ray path still works (binary auto-downloads to ~/.sentinel-sdk/bin).

fresh-test/connect-autonomous.mjs

@@ -0,0 +1,84 @@
+/**
+ * x402 Autonomous-path E2E — agent pays the node directly in P2P.
+ *
+ * No x402 server, no operator, no fee-grant. The agent holds its own P2P and
+ * calls connect() with protocol: 'v2ray' (zero-admin Windows path). Verifies the
+ * public IP actually changes, then disconnects.
+ *
+ * Run: AGENT_MNEMONIC="..." node fresh-test/connect-autonomous.mjs
+ */
+
+import { connect, disconnect, getBalance } from 'blue-js-sdk/ai-path';
+
+const MNEMONIC = process.env.AGENT_MNEMONIC;
+if (!MNEMONIC) {
+  console.error('ERROR: set AGENT_MNEMONIC in the environment');
+  process.exit(1);
+}
+
+const COUNTRY = process.env.AGENT_COUNTRY || 'US';
+const PROTOCOL = process.env.AGENT_PROTOCOL || 'v2ray'; // zero admin, ~70% of nodes
+
+const t0 = Date.now();
+const secs = (t) => ((Date.now() - t) / 1000).toFixed(1);
+
+async function publicIp() {
+  try {
+    const r = await fetch('https://api.ipify.org?format=json', { signal: AbortSignal.timeout(8000) });
+    return (await r.json()).ip;
+  } catch (e) {
+    return `unknown (${e.message})`;
+  }
+}
+
+console.log('='.repeat(64));
+console.log('  x402 AUTONOMOUS E2E — agent pays node directly (P2P)');
+console.log(`  protocol=${PROTOCOL}  country=${COUNTRY}`);
+console.log('='.repeat(64));
+
+// ai-path connect() registers cleanup handlers internally (idempotent) — no manual call needed.
+
+const bal = await getBalance(MNEMONIC);
+console.log(`  P2P balance: ${bal.p2p ?? bal.balance ?? JSON.stringify(bal)}`);
+
+const ipBefore = await publicIp();
+console.log(`  IP before:   ${ipBefore}`);
+
+console.log('\n  Connecting (pays 1 GB session directly to the node)...');
+let vpn;
+try {
+  vpn = await connect({
+    mnemonic: MNEMONIC,
+    country: COUNTRY,
+    protocol: PROTOCOL,
+    gigabytes: 1,
+    timeout: 120000,
+    onProgress: (step, detail) => console.log(`    [${step}] ${detail}`),
+  });
+} catch (err) {
+  console.error(`\n  CONNECT FAILED (${err.code || 'ERR'}): ${err.message}`);
+  process.exit(1);
+}
+
+// The SDK verifies the exit IP through the tunnel itself (vpn.ip). For V2Ray
+// (SOCKS proxy) this is the source of truth — a top-level fetch() on the host's
+// default route does NOT traverse the proxy, so compare vpn.ip to the host IP.
+const tunnelIp = vpn.ip ?? null;
+const routed = tunnelIp && tunnelIp !== ipBefore;
+console.log(`\n  CONNECTED in ${secs(t0)}s`);
+console.log(`    session:  ${vpn.sessionId}`);
+console.log(`    protocol: ${vpn.protocol ?? vpn.serviceType}`);
+console.log(`    node:     ${vpn.nodeAddress}`);
+console.log(`    tunnel IP:${tunnelIp ?? 'n/a'} (SDK-verified through tunnel)`);
+console.log(`  IP before:  ${ipBefore}`);
+console.log(`  Exit IP:    ${tunnelIp} — ${routed ? 'DIFFERENT ✓ routed' : 'same as host — NOT routed'}`);
+
+console.log('\n  Disconnecting...');
+try {
+  await disconnect();
+  console.log('  Disconnected cleanly.');
+} catch (err) {
+  console.error(`  Disconnect warning: ${err.message}`);
+}
+
+console.log(`\n  DONE in ${secs(t0)}s — routed: ${routed ? 'PASS' : 'CHECK'}`);

server/src/index.ts

@@ -302,7 +302,7 @@ app.get('/manifest', (_req, res) => {
       'Install (agent side only — you do NOT clone this repo): `npm install @x402/fetch @x402/evm viem blue-js-sdk`. That is the complete dependency set for paying and connecting. The express/@x402/express/dotenv packages are operator-only — ignore them.',
       `POST ${network === 'eip155:8453' ? 'https://x402.sentinel.co' : '/'}/vpn/connect/{1day|7days|30days} with { sentinelAddr } using @x402/fetch to auto-sign the 402. Tiers cost $0.033 / $0.233 / $1.00 USDC — pick the smallest that covers your need; $0.033 is enough to start. Add { country: "DE" } to get a node in a specific country (GET /nodes lists what is available). Payment is identical on every OS.`,
       'Connecting differs by OS. macOS & Linux: use the native CLI `sentinel-dvpncli` (go install github.com/sentinel-official/sentinel-dvpncli@latest — needs Go 1.24+). The CLI shells out to the system tunnel binary, so install `wireguard-tools` (provides `wg-quick`; most nodes are WireGuard) and, for V2Ray nodes, a `v2ray` binary on PATH. Then import the key (`printf \'%s\\n\\n\' "$MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test`), `tx session-start <nodeAddress> --subscription-id <id> --tx.fee-granter-addr <feeGranter> --tx.from-name agent --keyring.backend test`, resolve the id with `query sessions --account-addr <sent1...> --subscription-id <id> --output-format json`, then `connect <sessionId>` (sudo to bring the interface up). See sentinel.connectMacLinux. Only Fedora is unsupported (SELinux blocks VPNs).',
-'Windows: NO manual install and NO admin needed if you pin V2Ray. `connect({ mnemonic, subscriptionId, feeGranter, nodeAddress, protocol: "v2ray" })` auto-downloads the v2ray binary (userspace SOCKS5, ~70% of nodes) on first use — zero prerequisites beyond the npm install. Optionally `await setup()` first to pre-fetch it. WireGuard nodes (the other ~30%, faster) need admin ONCE for the MSI; the SDK checks admin before payment and refuses a WireGuard node when not elevated, so no funds are wasted — if you cannot elevate, stay on protocol: "v2ray". See sentinel.connectWindows.',
+'Windows: zero prereqs. `connect({ mnemonic, subscriptionId, feeGranter, nodeAddress, protocol: "v2ray" })` auto-downloads the v2ray binary (userspace SOCKS5, ~70% of nodes, no admin). WireGuard (~30%, faster) needs admin once; the SDK gates on admin BEFORE payment, so no funds are wasted. See sentinel.connectWindows.',
       'Tunnel is up. You paid as little as $0.033 USDC (1day) up to $1.00 (30day), zero gas on Base, zero gas on Sentinel.',
     ],
     network: {
@@ -524,7 +524,7 @@ app.get('/manifest', (_req, res) => {
         returns: { address: 'sent1... (use this as sentinelAddr)', mnemonic: 'string (persist this)' },
         note: 'Generate once per agent. The address goes in the request body; the mnemonic signs MsgStartSession.',
       },
-      platforms: 'Payment is identical on every OS; only the connect step differs. Windows is the zero-prereq path: with protocol: "v2ray" the JS SDK auto-downloads the tunnel binary (no admin, no manual install — see connectWindows / connect); WireGuard nodes there are an optional admin-once upgrade. macOS & Linux use the native CLI (sentinel-dvpncli + a system tunnel binary you install yourself — see connectMacLinux). Only Fedora is unsupported: its SELinux blocks VPN interfaces and cannot be bypassed programmatically.',
+      platforms: 'Payment is identical on every OS; only connect differs. Windows: zero-prereq with protocol: "v2ray" (see connectWindows). macOS & Linux: native CLI sentinel-dvpncli (see connectMacLinux). Fedora unsupported (SELinux blocks VPN interfaces).',
       connectMacLinux: {
         tool: 'sentinel-dvpncli',
         install: 'go install github.com/sentinel-official/sentinel-dvpncli@latest (Go 1.24+); binary lands in $(go env GOPATH)/bin',
@@ -542,18 +542,18 @@ app.get('/manifest', (_req, res) => {
       },
       connectWindows: {
         package: 'blue-js-sdk/ai-path',
-        zeroPrereq: 'Windows needs NO manual install and NO admin if you pass protocol: "v2ray". V2Ray is a userspace SOCKS5 proxy (no system access); connect() auto-downloads the v2ray binary to ~/.sentinel-sdk/bin on first use (no admin). This covers ~70% of the network (~630 nodes). This is the fully self-provisioning Windows path.',
         recommended: 'connect({ mnemonic, subscriptionId, feeGranter, nodeAddress, protocol: "v2ray" })',
-        requestHint: 'For a guaranteed-connectable node, also send { sentinelAddr, protocol: "v2ray" } in the POST body so the operator provisions a V2Ray node. GET /nodes?protocol=v2ray lists them.',
-        wireguardUpgrade: 'WireGuard nodes (the other ~30%, faster) need admin ONCE: the WireGuard MSI install and tunnel-service creation are elevated operations. setup() auto-installs the MSI only when run elevated (cscript run-admin.vbs setup.js triggers a single UAC prompt; a Windows service running as SYSTEM/admin needs none). The SDK checks admin BEFORE payment and refuses a WireGuard node when not elevated — so no USDC and no P2P is ever wasted. If you cannot elevate, stay on protocol: "v2ray".',
-        default: 'Calling connect() WITHOUT a protocol searches both node types — on a non-admin box it may pick a WireGuard node and fail the admin gate (no funds lost). Agents that cannot guarantee admin should always pin protocol: "v2ray".',
+        v2ray: 'protocol: "v2ray" = zero prereq. Userspace SOCKS5; connect() auto-downloads the binary to ~/.sentinel-sdk/bin (no admin, no manual install). ~70% of nodes (~630).',
+        wireguard: 'protocol: "wireguard" = ~30% of nodes, faster, but needs admin ONCE (MSI install). The SDK gates on admin BEFORE payment, so a non-admin box wastes no funds. Pin "v2ray" if you cannot elevate.',
+        noProtocol: 'Omitting protocol searches both types and may pick a WireGuard node that fails the admin gate (no funds lost). Pin "v2ray" if admin is not guaranteed.',
+        requestHint: 'To force a V2Ray node, POST { sentinelAddr, protocol: "v2ray" }. GET /nodes?protocol=v2ray lists them.',
       },
       connect: {
         package: 'blue-js-sdk/ai-path',
-        platform: 'Windows path (JS tunnel). On macOS/Linux use connectMacLinux (native CLI) instead.',
+        platform: 'Windows (JS tunnel). macOS/Linux use connectMacLinux.',
         fn: 'connect({ mnemonic, subscriptionId, feeGranter, nodeAddress, protocol: "v2ray" })',
-        protocolNote: 'protocol is optional but RECOMMENDED on Windows: "v2ray" = zero admin, zero manual install, auto-downloaded binary, ~70% of nodes. Omit it only if you have admin (then WireGuard nodes are also usable). See connectWindows.',
-        argsFrom: 'Pass response.success fields directly. mnemonic is the one from createWallet().',
+        protocolNote: 'On Windows pin protocol: "v2ray" (zero admin) unless you have admin. See connectWindows.',
+        argsFrom: 'Pass response.success fields directly. mnemonic is from createWallet().',
         returns: { connected: 'boolean', ip: 'string', protocol: 'wireguard | v2ray' },
         gasCost: '0 P2P — operator fee-grants MsgStartSession',
       },

server/src/sentinel.ts

@@ -487,7 +487,7 @@ async function buildProvisionResult(opts: {
     sentinelTxHash: opts.txHash,
     expiresAt: opts.expiresAt,
     operatorAddress,
-    instructions: `import { setup, connect } from 'blue-js-sdk/ai-path'; await setup(); /* installs V2Ray automatically if no tunnel binary is present */ await connect({ mnemonic, nodeAddress: '${recommended}', subscriptionId: '${opts.subscriptionId}', feeGranter: '${operatorAddress}' })`,
+    instructions: `import { connect } from 'blue-js-sdk/ai-path'; await connect({ mnemonic, protocol: 'v2ray', nodeAddress: '${recommended}', subscriptionId: '${opts.subscriptionId}', feeGranter: '${operatorAddress}' }); // protocol:'v2ray' = no admin; binary auto-installs. gas paid by feeGranter.`,
   };
 }