docs: Implementation plan for agent-relayed console proxy

2026-07-29 12:26:16 +01:00
parent 6d047e25ab
commit d3d8dba3ff
2 changed files with 2270 additions and 0 deletions
@@ -95,6 +95,14 @@ message ProxyServerMsg { oneof payload { bytes data = 1; ProxyClose close = 2; }
 message ProxyClose { string reason = 1; }
 ```

+Two implementation facts about this repo shape the above. The `pb` packages are
+**hand-written Go, not protoc output** — `vantage.proto` is documentation, and
+both `server/internal/grpc/pb` and `agent/internal/grpc/pb` are edited by hand
+and kept in sync manually. And the registered codec is JSON, so a `bytes` field
+travels as a base64 string: roughly 33% overhead on relayed traffic. That is
+accepted rather than fixed here, because introducing a second codec for one RPC
+is a larger change than this feature warrants. Relay chunks are 32 KiB.
+
 ## Security

 **The agent only ever dials `127.0.0.1`.** The port is the only field it takes