clawdbot/docs/refactor/gateway-client.md

summary, read_when

summary	read_when
Refactor notes for the macOS gateway client typed API migration (Dec 2025).	Refactoring macOS gateway client or typed gateway methods Auditing agent routing or channel semantics

Gateway Client Refactor (Dec 2025)

Goal: remove stringly-typed gateway calls from the macOS app, centralize routing/channel semantics, and improve error handling.

Progress

• Fold legacy “AgentRPC” into GatewayConnection (single layer; no separate client object).
• Typed gateway API: GatewayConnection.Method + requestDecoded/requestVoid + typed helpers (status/agent/chat/cron/etc).
• Centralize agent routing/channel semantics via GatewayAgentChannel + GatewayAgentInvocation.
• Improve gateway error model (structured GatewayResponseError + decoding errors include method).
• Migrate mac call sites to typed helpers (leave only intentionally dynamic forwarding paths).
• Convert remaining UI raw channel strings to GatewayAgentChannel (Cron editor).
• Cleanup naming: rename remaining tests/docs that still reference “RPC/AgentRPC”.

Notes

• Intentionally string-based:
  • BridgeServer dynamic request forwarding (method is data-driven).
  • ControlChannel request wrapper (generic escape hatch).

Notes / Non-goals

• No functional behavior changes intended (beyond better errors and removing “magic strings”).
• Keep changes incremental: introduce typed APIs first, then migrate call sites, then remove old helpers.