refactor: migrate chat panel to shared IPC helpers

EhabY · EhabY · commit abfbedcbabcd · 2026-04-20T21:05:50.000+03:00
Define ChatApi in shared and replace the ad-hoc {type, ...} message
handling with buildCommandHandlers / buildRequestHandlers plus
dispatchCommand / dispatchRequest. Outgoing notifications route
through a private notify() wrapper, mirroring tasksPanelProvider.

The iframe shim in the inline HTML keeps its own {type, payload}
contract with the Coder server, but its shim-to-extension side now
speaks the IPC wire format. Split the handler into handleFromIframe /
handleFromExtension + a toIframe helper + a showRetry builder so the
dispatch reads straight through.

Tests updated to the new wire format.
diff --git a/packages/shared/src/chat/api.ts b/packages/shared/src/chat/api.ts
@@ -0,0 +1,20 @@
+import { defineCommand, defineNotification } from "../ipc/protocol";
+
+/** The chat webview embeds an iframe that speaks to the Coder server. */
+export const ChatApi = {
+	/** Iframe reports it needs the session token. */
+	vscodeReady: defineCommand("coder:vscode-ready"),
+	/** Iframe reports the chat UI has rendered. */
+	chatReady: defineCommand("coder:chat-ready"),
+	/** Iframe requests an external navigation; same-origin only. */
+	navigate: defineCommand<{ url: string }>("coder:navigate"),
+
+	/** Push the current theme into the iframe. */
+	setTheme: defineNotification<{ theme: "light" | "dark" }>("coder:set-theme"),
+	/** Push the session token to bootstrap iframe auth. */
+	authBootstrapToken: defineNotification<{ token: string }>(
+		"coder:auth-bootstrap-token",
+	),
+	/** Signal that auth could not be obtained. */
+	authError: defineNotification<{ error: string }>("coder:auth-error"),
+} as const;
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
@@ -16,3 +16,6 @@ export {
 	type SpeedtestInterval,
 	type SpeedtestResult,
 } from "./speedtest/api";
+
+// Chat API
+export { ChatApi } from "./chat/api";
diff --git a/src/webviews/chat/chatPanelProvider.ts b/src/webviews/chat/chatPanelProvider.ts
@@ -1,22 +1,36 @@
 import * as vscode from "vscode";
 
+import {
+	buildCommandHandlers,
+	buildRequestHandlers,
+	ChatApi,
+	type NotificationDef,
+} from "@repo/shared";
+
 import { type CoderApi } from "../../api/coderApi";
 import { type Logger } from "../../logging/logger";
-import { getNonce } from "../util";
+import {
+	dispatchCommand,
+	dispatchRequest,
+	getNonce,
+	isIpcCommand,
+	isIpcRequest,
+	notifyWebview,
+} from "../util";
 
 /**
  * Provides a webview that embeds the Coder agent chat UI.
  * Authentication flows through postMessage:
  *
  *   1. The iframe loads /agents/{id}/embed on the Coder server.
- *   2. The embed page detects the user is signed out and sends
+ *   2. The embed page detects the user is signed out and posts
  *      { type: "coder:vscode-ready" } to window.parent.
- *   3. Our webview relays this to the extension host.
- *   4. The extension host replies with the session token.
- *   5. The webview forwards { type: "coder:vscode-auth-bootstrap" }
- *      with the token back into the iframe.
- *   6. The embed page calls API.setSessionToken(token), re-fetches
- *      the authenticated user, and renders the chat UI.
+ *   3. Our shim relays that to the extension as a ChatApi.vscodeReady
+ *      command.
+ *   4. The extension pushes the session token back with
+ *      ChatApi.authBootstrapToken.
+ *   5. The shim forwards it into the iframe, which calls
+ *      API.setSessionToken and re-fetches the user.
  */
 export class ChatPanelProvider
 	implements vscode.WebviewViewProvider, vscode.Disposable
@@ -28,6 +42,13 @@ export class ChatPanelProvider
 	private chatId: string | undefined;
 	private authRetryTimer: ReturnType<typeof setTimeout> | undefined;
 
+	private readonly commandHandlers = buildCommandHandlers(ChatApi, {
+		vscodeReady: () => this.sendAuthToken(),
+		chatReady: () => this.sendTheme(),
+		navigate: ({ url }) => this.handleNavigate(url),
+	});
+	private readonly requestHandlers = buildRequestHandlers(ChatApi, {});
+
 	constructor(
 		private readonly client: Pick<CoderApi, "getHost" | "getSessionToken">,
 		private readonly logger: Logger,
@@ -41,11 +62,17 @@ export class ChatPanelProvider
 			: "dark";
 	}
 
+	private notify<D>(
+		def: NotificationDef<D>,
+		...args: D extends void ? [] : [data: D]
+	): void {
+		if (this.view) {
+			notifyWebview(this.view.webview, def, ...args);
+		}
+	}
+
 	private sendTheme(): void {
-		this.view?.webview.postMessage({
-			type: "coder:set-theme",
-			theme: this.getTheme(),
-		});
+		this.notify(ChatApi.setTheme, { theme: this.getTheme() });
 	}
 
 	/**
@@ -75,8 +102,20 @@ export class ChatPanelProvider
 		this.view = webviewView;
 		webviewView.webview.options = { enableScripts: true };
 		this.disposables.push(
-			webviewView.webview.onDidReceiveMessage((msg: unknown) => {
-				this.handleMessage(msg);
+			webviewView.webview.onDidReceiveMessage((message: unknown) => {
+				if (isIpcRequest(message)) {
+					void dispatchRequest(
+						message,
+						this.requestHandlers,
+						webviewView.webview,
+						{ logger: this.logger },
+					);
+				} else if (isIpcCommand(message)) {
+					void dispatchCommand(message, this.commandHandlers, {
+						logger: this.logger,
+						showErrorToUser: () => false,
+					});
+				}
 			}),
 			vscode.window.onDidChangeActiveColorTheme(() => {
 				this.sendTheme();
@@ -114,38 +153,19 @@ export class ChatPanelProvider
 		webview.html = this.getIframeHtml(embedUrl, coderUrl);
 	}
 
-	private handleMessage(message: unknown): void {
-		if (typeof message !== "object" || message === null) {
+	private handleNavigate(url: string): void {
+		const coderUrl = this.client.getHost();
+		if (!url || !coderUrl) {
 			return;
 		}
-		const msg = message as { type?: string; payload?: { url?: string } };
-		switch (msg.type) {
-			case "coder:vscode-ready":
-				this.sendAuthToken();
-				break;
-			case "coder:chat-ready":
-				this.sendTheme();
-				break;
-			case "coder:navigate": {
-				const url = msg.payload?.url;
-				const coderUrl = this.client.getHost();
-				if (url && coderUrl) {
-					try {
-						const resolved = new URL(url, coderUrl);
-						const expected = new URL(coderUrl);
-						if (resolved.origin === expected.origin) {
-							void vscode.env.openExternal(
-								vscode.Uri.parse(resolved.toString()),
-							);
-						}
-					} catch {
-						this.logger.warn(`Chat: invalid navigate URL: ${url}`);
-					}
-				}
-				break;
+		try {
+			const resolved = new URL(url, coderUrl);
+			const expected = new URL(coderUrl);
+			if (resolved.origin === expected.origin) {
+				void vscode.env.openExternal(vscode.Uri.parse(resolved.toString()));
 			}
-			default:
-				break;
+		} catch {
+			this.logger.warn(`Chat: invalid navigate URL: ${url}`);
 		}
 	}
 
@@ -178,17 +198,13 @@ export class ChatPanelProvider
 				"Chat iframe requested auth but no session token available " +
 					"after all retries",
 			);
-			this.view?.webview.postMessage({
-				type: "coder:auth-error",
+			this.notify(ChatApi.authError, {
 				error: "No session token available. Please sign in and retry.",
 			});
 			return;
 		}
 		this.logger.info("Chat: forwarding token to iframe");
-		this.view?.webview.postMessage({
-			type: "coder:auth-bootstrap-token",
-			token,
-		});
+		this.notify(ChatApi.authBootstrapToken, { token });
 	}
 
 	private getIframeHtml(embedUrl: string, allowedOrigin: string): string {
@@ -246,53 +262,72 @@ export class ChatPanelProvider
         status.style.display = 'none';
       });
 
-      window.addEventListener('message', (event) => {
-        const data = event.data;
-        if (!data || typeof data !== 'object') return;
+      // Shim sits between two wire formats. The iframe speaks
+      // { type, payload } (a contract owned by the Coder server).
+      // The extension speaks the IPC protocol: commands are
+      // { method, params } and notifications are { type, data }.
+      // See packages/webview-shared/README.md.
+      const toIframe = (type, payload) => {
+        iframe.contentWindow.postMessage({ type, payload }, '${allowedOrigin}');
+      };
 
-        if (event.source === iframe.contentWindow) {
-          if (data.type === 'coder:vscode-ready') {
-            status.textContent = 'Authenticating…';
-            vscode.postMessage({ type: 'coder:vscode-ready' });
-          }
-          if (data.type === 'coder:chat-ready') {
-            vscode.postMessage({ type: 'coder:chat-ready' });
-          }
-          if (data.type === 'coder:navigate') {
-            vscode.postMessage(data);
-          }
-          return;
-        }
+      const showRetry = (error) => {
+        status.textContent = '';
+        status.appendChild(document.createTextNode(error || 'Authentication failed.'));
+        const btn = document.createElement('button');
+        btn.id = 'retry-btn';
+        btn.textContent = 'Retry';
+        btn.addEventListener('click', () => {
+          status.textContent = 'Authenticating…';
+          vscode.postMessage({ method: 'coder:vscode-ready' });
+        });
+        status.appendChild(document.createElement('br'));
+        status.appendChild(btn);
+        status.style.display = 'block';
+        iframe.style.display = 'none';
+      };
 
-        if (data.type === 'coder:auth-bootstrap-token') {
-          status.textContent = 'Signing in…';
-          iframe.contentWindow.postMessage({
-            type: 'coder:vscode-auth-bootstrap',
-            payload: { token: data.token },
-          }, '${allowedOrigin}');
+      const handleFromIframe = (msg) => {
+        switch (msg.type) {
+          case 'coder:vscode-ready':
+            status.textContent = 'Authenticating…';
+            vscode.postMessage({ method: 'coder:vscode-ready' });
+            return;
+          case 'coder:chat-ready':
+            vscode.postMessage({ method: 'coder:chat-ready' });
+            return;
+          case 'coder:navigate':
+            vscode.postMessage({
+              method: 'coder:navigate',
+              params: { url: msg.payload?.url },
+            });
+            return;
         }
+      };
 
-        if (data.type === 'coder:set-theme') {
-          iframe.contentWindow.postMessage({
-            type: 'coder:set-theme',
-            payload: { theme: data.theme },
-          }, '${allowedOrigin}');
+      const handleFromExtension = (msg) => {
+        const data = msg.data || {};
+        switch (msg.type) {
+          case 'coder:auth-bootstrap-token':
+            status.textContent = 'Signing in…';
+            toIframe('coder:vscode-auth-bootstrap', { token: data.token });
+            return;
+          case 'coder:set-theme':
+            toIframe('coder:set-theme', { theme: data.theme });
+            return;
+          case 'coder:auth-error':
+            showRetry(data.error);
+            return;
         }
+      };
 
-        if (data.type === 'coder:auth-error') {
-          status.textContent = '';
-          status.appendChild(document.createTextNode(data.error || 'Authentication failed.'));
-          const btn = document.createElement('button');
-          btn.id = 'retry-btn';
-          btn.textContent = 'Retry';
-          btn.addEventListener('click', () => {
-            status.textContent = 'Authenticating…';
-            vscode.postMessage({ type: 'coder:vscode-ready' });
-          });
-          status.appendChild(document.createElement('br'));
-          status.appendChild(btn);
-          status.style.display = 'block';
-          iframe.style.display = 'none';
+      window.addEventListener('message', (event) => {
+        const msg = event.data;
+        if (!msg || typeof msg !== 'object') return;
+        if (event.source === iframe.contentWindow) {
+          handleFromIframe(msg);
+        } else {
+          handleFromExtension(msg);
         }
       });
     })();
diff --git a/src/webviews/speedtest/speedtestPanel.ts b/src/webviews/speedtest/speedtestPanel.ts
@@ -55,7 +55,8 @@ export function showSpeedtestChart(
 	// canvas pixels bake in theme colors. Re-send on visibility and theme
 	// changes so the chart rehydrates.
 	const payload: SpeedtestData = { workspaceName, result };
-	const sendData = () => notifyWebview(panel.webview, SpeedtestApi.data, payload);
+	const sendData = () =>
+		notifyWebview(panel.webview, SpeedtestApi.data, payload);
 	sendData();
 
 	// Both builders emit a compile error if any command or request in the
diff --git a/test/unit/webviews/chat/chatPanelProvider.test.ts b/test/unit/webviews/chat/chatPanelProvider.test.ts
@@ -92,11 +92,11 @@ describe("ChatPanelProvider", () => {
 			windowMock.__setActiveColorThemeKind(kind);
 			const { sendFromWebview, postMessage } = createHarness();
 
-			sendFromWebview({ type: "coder:chat-ready" });
+			sendFromWebview({ method: "coder:chat-ready" });
 
 			expect(findPostedMessage(postMessage, "coder:set-theme")).toEqual({
 				type: "coder:set-theme",
-				theme: expected,
+				data: { theme: expected },
 			});
 		});
 
@@ -108,7 +108,7 @@ describe("ChatPanelProvider", () => {
 
 			expect(postMessage).toHaveBeenCalledWith({
 				type: "coder:set-theme",
-				theme: "light",
+				data: { theme: "light" },
 			});
 		});
 	});
@@ -117,13 +117,13 @@ describe("ChatPanelProvider", () => {
 		it("sends auth token on coder:vscode-ready", () => {
 			const { sendFromWebview, postMessage } = createHarness();
 
-			sendFromWebview({ type: "coder:vscode-ready" });
+			sendFromWebview({ method: "coder:vscode-ready" });
 
 			expect(
 				findPostedMessage(postMessage, "coder:auth-bootstrap-token"),
 			).toEqual({
 				type: "coder:auth-bootstrap-token",
-				token: "test-token",
+				data: { token: "test-token" },
 			});
 		});
 	});
@@ -133,8 +133,8 @@ describe("ChatPanelProvider", () => {
 			const { sendFromWebview } = createHarness();
 
 			sendFromWebview({
-				type: "coder:navigate",
-				payload: { url: "/templates" },
+				method: "coder:navigate",
+				params: { url: "/templates" },
 			});
 
 			expect(vscode.env.openExternal).toHaveBeenCalledWith(
@@ -145,7 +145,7 @@ describe("ChatPanelProvider", () => {
 		it("ignores navigate without url payload", () => {
 			const { sendFromWebview } = createHarness();
 
-			sendFromWebview({ type: "coder:navigate" });
+			sendFromWebview({ method: "coder:navigate", params: {} });
 
 			expect(vscode.env.openExternal).not.toHaveBeenCalled();
 		});
@@ -154,8 +154,8 @@ describe("ChatPanelProvider", () => {
 			const { sendFromWebview } = createHarness();
 
 			sendFromWebview({
-				type: "coder:navigate",
-				payload: { url: "https://evil.com/steal" },
+				method: "coder:navigate",
+				params: { url: "https://evil.com/steal" },
 			});
 
 			expect(vscode.env.openExternal).not.toHaveBeenCalled();
