VAGUS

Overview

The Node client is a CLI wrapper around MCP-over-WebSocket to VAGUS relay. It supports pair/connect, read/call/list operations, and long-running subscriptions with JSONL output.

Setup

cd ~/.openclaw/skills/vagus/scripts
npm install
node vagus-connect.js pair <PAIR_CODE>
node vagus-connect.js status

CLI Commands

node {baseDir}/scripts/vagus-connect.js <command> [args]

JSONL Contract

All outputs are line-delimited JSON objects.

{"type":"paired","session_token":"..."}
{"type":"capabilities","resources":["..."],"tools":["..."]}
{"type":"resource","uri":"vagus://device/screen","data":{"screen_on":true,"locked":false}}
{"type":"stream_state","uri":"vagus://device/screen","status":"fresh","freshness_ms":132,"thresholds":{"observed_p95_interval_ms":1000,"delayed_after_ms":2500,"stale_after_ms":6000,"unavailable_after_ms":20000}}
{"type":"result","tool":"notify","success":true,"data":{"content":[{"type":"text","text":"{\"ok\":true}"}]}}

Request Metadata and Trace IDs

MCP response and notification envelopes include a top-level trace_id field when available. This identifier provides end-to-end correlation across request handling, outbound notifications, and server audit logs.

{
  "jsonrpc": "2.0",
  "id": 3,
  "trace_id": "43818824:tools/call:5545a8fa214dd67e:405164970b59034e",
  "result": {
    "content": [ { "type": "text", "text": "{\"ok\":true,\"id\":9098}" } ],
    "isError": false
  }
}

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "trace_id": "43818824:resources/subscribe:5545a8fa214dd67e:aa3d70c94091b898",
  "params": {
    "sessionId": "5545a8fa214dd67e",
    "uri": "vagus://device/screen",
    "data": { "screen_on": true, "locked": false, "ts": 1772043993616 },
    "ts": 1772043993632
  }
}

The vagus-connect.js wrapper emits normalized JSONL and preserves MCP correlation context (including trace_id) in the mcp object for operational commands (read/call/list/subscribe/unsubscribe and streamed updates). If you need the full raw JSON-RPC envelope, capture raw MCP frames in custom integrations.

Managed Streaming

For persistent field operation, prefer vagus-manager.js over multiple independent subscribe processes. The manager keeps one MCP session alive, auto-reconnects, re-subscribes active URIs, and tracks adaptive freshness per stream.

node {baseDir}/scripts/vagus-manager.js
node {baseDir}/scripts/vagus-manager.js add vagus://sensors/location
node {baseDir}/scripts/vagus-manager.js remove vagus://inference/attention
node {baseDir}/scripts/vagus-manager.js list
node {baseDir}/scripts/vagus-manager.js status

Stale detection is dynamic: thresholds are learned from observed inter-arrival timing only. The manager does not assume a hard-coded cadence per resource.

Resources

• vagus://session/info
• vagus://sensors/motion, activity, activity_recognition, location, environment
• vagus://inference/attention, indoor_confidence, sleep_likelihood, notification_timing
• vagus://device/connectivity, screen, battery, clipboard, notifications
• vagus://io/type_* dynamic onboard sensor resources (device-specific)

node {baseDir}/scripts/vagus-connect.js read vagus://session/info
node {baseDir}/scripts/vagus-connect.js subscribe vagus://device/screen

Subscriptions vs Read-Only

Before using subscribe, confirm the URI supports streaming semantics on the server.

Tools

node {baseDir}/scripts/vagus-connect.js call sms/send '{"to":"+14388090319","body":"Test message"}'
node {baseDir}/scripts/vagus-connect.js call intent/open_url '{"url":"https://withvagus.com"}'
node {baseDir}/scripts/vagus-connect.js call io/set_subscription_resolution '{"resolutionMs":30000}'
node {baseDir}/scripts/vagus-connect.js call infer/set_subscription_resolution '{"resolutionMs":30000}'
node {baseDir}/scripts/vagus-connect.js call calendar/create_event '{"title":"dayclub","startTimeMs":1771772400000,"endTimeMs":1771776000000,"allDay":false}'

io/set_subscription_resolution controls cadence for all vagus://io/type_* subscriptions and is gated by the device-side toggle Allow agent to set resolution (default off). infer/set_subscription_resolution controls infer cadence and is gated by Allow agent to set infer resolution (default off).

User Permissions (Server-Side)

Permissions are enforced in the VAGUS Android app. The Node client can issue MCP reads and tool calls, but execution is gated by user-configured capability toggles and runtime approval prompts.

Expected automation behavior: on permission denial/timeout, return a clear user action ("approve in VAGUS" or "enable permission"), then retry once.

Timeouts and Liveness

Error Codes