Add companion runtime gateway client foundation

docs/plans/2026-02-16-companion-runtime-client-foundation-checklist.md

@@ -0,0 +1,37 @@
+# Companion Runtime Client Foundation Checklist (2026-02-16)
+
+## Scope
+
+- Add a reusable Node/WebSocket runtime client for companion apps to call gateway node/system RPC methods without manually handling request IDs, pending maps, or error-code parsing.
+- Keep API focused on current companion milestones:
+  - `node.register`
+  - `node.capabilities.get`
+  - `node.location.set/get`
+  - `node.status.set`
+  - `node.push_token.set`
+  - `system.capabilities`
+  - `system.nodes`
+
+## Implementation
+
+- Added `src/companion/runtimeClient.ts`:
+  - `CompanionRuntimeClient` typed wrapper around gateway JSON-RPC over `ws`.
+  - `GatewayRpcError` carrying gateway error code + message.
+  - Connection lifecycle (`connect`, `disconnect`, `connected`) and typed `call<T>()`.
+  - Method-specific wrappers for node/system companion RPCs.
+  - Token query-param support for gateway bearer auth.
+- Added `src/companion/index.ts` exports for companion runtime integration.
+- Added `src/companion/runtimeClient.test.ts` integration coverage against live `GatewayServer` fixture.
+
+## Validation
+
+- Companion runtime tests:
+  - registration + capability flow
+  - status/location/push updates and `system.nodes` visibility
+  - RPC error mapping into `GatewayRpcError`
+
+## Docs Updated
+
+- `README.md` (Gateway Node Capability Negotiation section): references `src/companion/runtimeClient.ts` helper.
+- `docs/api/PROTOCOL.md`: implementation reference updated with runtime client helper.
+- `docs/architecture/CONTRIBUTOR_MAP.md`: repo tour now includes `src/companion/`.

docs/plans/state.json

@@ -707,6 +707,25 @@
       ],
       "test_status": "pnpm test:run src/channels/zalo/adapter.test.ts src/daemon/channels.test.ts src/config/schema.test.ts src/gateway/handlers/services.test.ts + pnpm typecheck + pnpm build passing"
     },
+    "companion-runtime-client-foundation": {
+      "file": "2026-02-16-companion-runtime-client-foundation-checklist.md",
+      "status": "completed",
+      "date": "2026-02-16",
+      "updated": "2026-02-16",
+      "summary": "Added a reusable companion runtime gateway client (`CompanionRuntimeClient`) for Node/WebSocket JSON-RPC with typed wrappers for node registration/capability/status/location/push and operator system capability/node listing methods, including RPC error-code mapping and integration tests.",
+      "files_created": [
+        "docs/plans/2026-02-16-companion-runtime-client-foundation-checklist.md",
+        "src/companion/runtimeClient.ts",
+        "src/companion/runtimeClient.test.ts",
+        "src/companion/index.ts"
+      ],
+      "files_modified": [
+        "README.md",
+        "docs/api/PROTOCOL.md",
+        "docs/architecture/CONTRIBUTOR_MAP.md"
+      ],
+      "test_status": "pnpm test:run src/companion/runtimeClient.test.ts + pnpm typecheck + pnpm build passing"
+    },
     "qmd-backend": {
       "file": "2026-02-16-qmd-backend-checklist.md",
       "status": "completed",
@@ -3268,7 +3287,7 @@
     }
   },
   "overall_progress": {
-    "total_test_count": 1814,
+    "total_test_count": 1817,
     "all_tests_passing": true,
     "p0_completion": "3/3 (100%)",
     "p1_completion": "4/4 (100%)",
@@ -3288,7 +3307,7 @@
     "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: companion app runtime clients (macOS/iOS/Android implementation) — open next scoped implementation checklist"
+    "next_up": "OpenClaw gap: implement macOS/iOS/Android companion runtime clients on top of `src/companion/runtimeClient.ts`"
   },
   "soul_md_and_cron_create": {
     "date": "2026-02-11",