let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add ws chat attachments

Browse Source
This commit is contained in:
Peter Steinberger
2025-12-09 23:16:57 +01:00
parent e80e5b0801
commit 1dd5c97ae0
25 changed files with 987 additions and 882 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/webchat.md
View File

@@ -1,5 +1,5 @@
---
summary: "Loopback WebChat server and SSH tunnel usage for chat UI"
summary: "Loopback WebChat static host and Gateway WS usage for chat UI"
read_when:
- Debugging or configuring WebChat access
---
@@ -8,23 +8,21 @@ read_when:
Updated: 2025-12-09
## What it is
- A local web UI for chatting with the Gateway.
- A local web UI for chatting with the Gateway, now WS-only for data.
- Static assets served by the WebChat HTTP server (default port **18788**, configurable).
- The WebChat backend holds a single WebSocket connection to the Gateway (`ws://127.0.0.1:18789` by default) for all control/data: history fetch, sends, agent runs, presence.
- The browser/WebView connects directly to the Gateway WebSocket (`ws://127.0.0.1:18789` by default) for history, sends, and events. No file watching or HTTP RPC.
- Trust model: access is granted by being on localhost or inside your SSH/Tailscale tunnel. No additional auth prompts once you can reach the box.
- `webchat.gatewayPort` config can point at a non-default Gateway port if needed.
## Endpoints
- UI is now served at the root: `http://127.0.0.1:<port>/` (legacy `/webchat/` still works).
- `GET /webchat/info?session=<key>` (alias `/info`) → `{ port, sessionId, initialMessages, basePath }` plus history from the Gateway session store.
- `GET /` (or `/webchat/*`) → static assets.
- `POST /webchat/rpc` (alias `/rpc`) → proxies a chat/agent action through the Gateway connection and returns `{ ok, payloads?, error? }`.
- UI is served at the root: `http://127.0.0.1:<port>/` (legacy `/webchat/` still works).
- `GET /` (or `/webchat/*`) → static assets only. No RPC endpoints.
- Data plane is entirely on the Gateway WS (`ws://127.0.0.1:<gatewayPort>`): methods `chat.history`, `chat.send`; events `chat`, `presence`, `tick`, `health`.
## How it connects
- On startup, the WebChat server dials the Gateway WebSocket and performs the mandatory `hello` handshake; the `hello-ok` snapshot seeds presence + health immediately.
- All outgoing sends/agent calls are requests on that WS; streamed events (`agent`, `presence`, `tick`) are forwarded to the browser client.
- If a seq gap is detected in Gateway events, WebChat auto-refreshes health + presence and broadcasts a `gateway-refresh` to connected browsers.
- If the Gateway WS is unavailable, WebChat fails fast and surfaces the error in the UI.
- Browser/WebView performs Gateway WS `hello`, then calls `chat.history` for bootstrap and `chat.send` for sends; listens to `chat/presence/tick/health` events.
- No session file watching. History comes from the Gateway via `chat.history`.
- If Gateway WS is unavailable, the UI surfaces the error and blocks send.
## Remote use
- SSH tunnel example: `ssh -N -L 18788:127.0.0.1:18788 -L 18789:127.0.0.1:18789 user@host`.
@@ -36,10 +34,10 @@ Updated: 2025-12-09
- Gateway WS port is set by `clawdis gateway --port`; WebChat expects it at 18789 unless overridden.
## Failure handling
- Clear UI error when the Gateway handshake fails or the WS drops.
- UI errors when the Gateway handshake fails or the WS drops; no HTTP fallback.
- WebChat does not attempt fallback transports; the Gateway WS is required.
## Dev notes
- Assets live in `apps/macos/Sources/Clawdis/Resources/WebChat`.
- Server implementation: `src/webchat/server.ts`.
- macOS glue: `WebChatWindow.swift` + `WebChatTunnel` for SSH -L helpers.
- Static host: `src/webchat/server.ts` (loopback-only HTTP).
- macOS glue: `WebChatWindow.swift` + `WebChatTunnel` for SSH -L helpers; WKWebView talks directly to Gateway WS.