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

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/.