Add node location access RPCs and operator visibility

2026-02-16 12:30:55 -08:00
parent 1d16cd54e6
commit fe8674e108
19 changed files with 693 additions and 15 deletions
@@ -604,17 +604,22 @@ Register node role/capabilities for the current WebSocket connection.

 Return negotiated capabilities for the currently registered node connection.

-#### `system.capabilities`
+#### `node.location.set`

-Return gateway protocol version, node policy status, and feature-gate snapshot.
+Update the last-known location for the currently registered node connection.
+Requires `server.nodes.enabled: true` and `server.nodes.location.enabled: true`.

 **Request:**
 ```json
 {
-  "id": 8,
-  "method": "agent.cancel",
+  "id": 10,
+  "method": "node.location.set",
  "params": {
-    "sessionId": "telegram:123456"
+    "latitude": 37.7749,
+    "longitude": -122.4194,
+    "accuracyMeters": 12.4,
+    "source": "gps",
+    "capturedAt": 1763241200000
  }
 }
 ```
@@ -622,13 +627,63 @@ Return gateway protocol version, node policy status, and feature-gate snapshot.
 **Response:**
 ```json
 {
-  "id": 8,
+  "id": 10,
  "result": {
-    "cancelled": true
+    "updated": true,
+    "node": { "id": "companion-desktop", "role": "companion" },
+    "location": {
+      "latitude": 37.7749,
+      "longitude": -122.4194,
+      "accuracyMeters": 12.4,
+      "source": "gps",
+      "capturedAt": 1763241200000,
+      "receivedAt": 1763241200451
+    }
  }
 }
 ```

+#### `node.location.get`
+
+Return the stored last-known location for the currently registered node connection.
+
+#### `system.capabilities`
+
+Return gateway protocol version, node policy status, and feature-gate snapshot.
+
+**Request:**
+```json
+{
+  "id": 11,
+  "method": "system.capabilities"
+}
+```
+
+**Response:**
+```json
+{
+  "id": 11,
+  "result": {
+    "protocol": { "version": 1 },
+    "nodes": {
+      "enabled": true,
+      "locationEnabled": true,
+      "allowedRoles": ["companion"],
+      "registered": true,
+      "role": "companion",
+      "nodeId": "companion-desktop"
+    },
+    "featureGates": {
+      "ui.canvas": true
+    }
+  }
+}
+```
+
+#### `system.location`
+
+Return the operator-facing snapshot of registered node locations.
+
 #### `agent.setToolUseCallback`

 Set callback for tool use events (for confirmation UI).
@@ -0,0 +1,53 @@
+# Location Access Checklist
+
+**Date:** 2026-02-16  
+**Scope:** Close OpenClaw "Location access" gap using Flynn's node capability foundation.
+
+## Goal
+
+Provide a safe, node-scoped location API so companion clients can publish last-known location and operators can inspect it.
+
+## Implemented
+
+- Added node location protocol parsing:
+  - `parseNodeLocationSetParams()`
+  - `parseNodeLocationGetParams()`
+- Added node RPC methods:
+  - `node.location.set`
+  - `node.location.get`
+- Added operator visibility method:
+  - `system.location`
+- Extended node state model with stored location payload.
+- Added explicit location feature gate in config:
+  - `server.nodes.location.enabled` (default `false`)
+- Wired daemon config to gateway runtime and node handlers.
+- Added runtime patch support for:
+  - `config.patch` key `server.nodes.location.enabled`
+- Updated docs:
+  - `README.md` gateway node section
+  - `docs/api/PROTOCOL.md` node/system method docs
+
+## Tests
+
+- `src/gateway/protocol.test.ts`
+  - Added validation tests for `node.location.set/get` params parsing.
+- `src/gateway/handlers/node.test.ts`
+  - Added location set/get lifecycle tests.
+  - Added disabled-gate rejection test.
+- `src/gateway/handlers/handlers.test.ts`
+  - Added `system.location` handler tests.
+  - Added config patch test for `server.nodes.location.enabled`.
+- `src/gateway/server.test.ts`
+  - Added integration test for node registration + location set/get flow.
+- `src/config/schema.test.ts`
+  - Added default/custom tests for `server.nodes.location.enabled`.
+- `src/gateway/auth.test.ts`
+  - Added role-scope authorization test for `node.location.set`.
+
+## Validation Run
+
+```bash
+pnpm test:run src/gateway/protocol.test.ts src/gateway/auth.test.ts src/gateway/handlers/node.test.ts src/gateway/handlers/handlers.test.ts src/gateway/server.test.ts src/config/schema.test.ts
+pnpm typecheck
+pnpm build
+```
@@ -466,6 +466,35 @@
      ],
      "test_status": "pnpm test:run src/channels/registry.test.ts src/gateway/handlers/handlers.test.ts + pnpm typecheck passing"
    },
+    "location-access": {
+      "file": "2026-02-16-location-access-checklist.md",
+      "status": "completed",
+      "date": "2026-02-16",
+      "updated": "2026-02-16",
+      "summary": "Implemented node-scoped location access on top of gateway node capability negotiation: added `node.location.set/get` RPCs, operator `system.location` visibility, config gate `server.nodes.location.enabled` (default false), runtime config patch support, tests, and docs updates.",
+      "files_created": [
+        "docs/plans/2026-02-16-location-access-checklist.md"
+      ],
+      "files_modified": [
+        "src/gateway/protocol.ts",
+        "src/gateway/protocol.test.ts",
+        "src/gateway/handlers/node.ts",
+        "src/gateway/handlers/node.test.ts",
+        "src/gateway/handlers/system.ts",
+        "src/gateway/handlers/handlers.test.ts",
+        "src/gateway/handlers/config.ts",
+        "src/gateway/server.ts",
+        "src/gateway/server.test.ts",
+        "src/gateway/auth.test.ts",
+        "src/daemon/services.ts",
+        "src/config/schema.ts",
+        "src/config/schema.test.ts",
+        "config/default.yaml",
+        "README.md",
+        "docs/api/PROTOCOL.md"
+      ],
+      "test_status": "pnpm test:run src/gateway/protocol.test.ts src/gateway/auth.test.ts src/gateway/handlers/node.test.ts src/gateway/handlers/handlers.test.ts src/gateway/server.test.ts src/config/schema.test.ts + pnpm typecheck + pnpm build passing"
+    },
    "qmd-backend": {
      "file": "2026-02-16-qmd-backend-checklist.md",
      "status": "completed",
@@ -3042,12 +3071,12 @@
    "tier2_completion": "4/4 (100%) — inbound webhooks, vector memory search, Dockerfile, heartbeat monitor",
    "tier3_completion": "5/5 (100%) — lane queue, credential redaction, web UI token dashboard, xAI (Grok) provider, Voyage AI embeddings",
    "tier4_completion": "4/4 (100%) — gateway lock, shell completion, Tailscale Serve/Funnel, DM pairing codes",
-    "feature_gap_scorecard": "118/128 match (92%), 0 partial (0%), 10 missing (8%)",
+    "feature_gap_scorecard": "119/128 match (93%), 0 partial (0%), 9 missing (7%)",
    "operator_dx_milestone": "Phase 3 (Live Ops Dashboard): 2/2 plans complete — milestone done",
    "gmail_auth_cli": "flynn gmail-auth command implemented with OAuth2 flow, doctor check, config routed to Telegram",
    "native_audio_support": "completed — smart routing for native audio (Gemini/OpenAI/GitHub) vs Whisper transcription fallback",
    "remaining_phases_completion": "Phase 1: 3/3 (100%) — context levels, command registry, memory structure. Phase 2: 3/3 (100%) — component registry, confidence routing, history index. Phase 3: 2/2 (100%) — adaptive memory/compaction, truthfulness/autonomy hardening",
-    "next_up": "OpenClaw gap: Location access (open next scoped implementation checklist)"
+    "next_up": "OpenClaw gap: Canvas / A2UI (open next scoped implementation checklist)"
  },
  "soul_md_and_cron_create": {
    "date": "2026-02-11",