refactor(agent-service): extract WebSocket message types into types/ws

Move the inline WS message definitions out of server.ts into a dedicated
types/ws module, modeled as discriminated unions rather than one
all-optional interface:

- client.ts: WsClientRequest = WsClientRequestPrompt | WsClientRequestStopCommand
- server.ts: WsServerMessage union (init/step/state/complete/error/headChange) + OperatorResultSummaryWs
- index.ts: barrel, re-exported from the types barrel

The client->server wire discriminator changes from "message"/"stop" to
"prompt"/"command" (stop becomes commandType: "stop"); server->client `type`
values are unchanged. server.ts parses WsClientRequest and switches on the new
shapes, and the frontend WS sends are updated in lockstep.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012qFkyrpTd5PrkNBPcBeo4Q

Author: bobbai00

agent-service/src/server.ts

@@ -39,7 +39,8 @@ import type {
   AgentSettingsApi,
   ReActStep,
 } from "./types/agent";
-import { OperatorResultSerializationMode } from "./types/agent";
+import { AgentState, OperatorResultSerializationMode } from "./types/agent";
+import type { WsClientRequest, WsServerMessage, WsServerInitMessage, OperatorResultSummaryWs } from "./types/ws";
 
 const agentStore = new Map<string, TexeraAgent>();
 let agentCounter = 0;
@@ -410,37 +411,6 @@ const agentsRouter = new Elysia({ prefix: "/agents" })
     }
   );
 
-interface WsMessage {
-  type: "message" | "stop";
-  content?: string;
-  messageSource?: "chat" | "feedback";
-}
-
-interface OperatorResultSummaryWs {
-  state: string;
-  inputTuples: number;
-  outputTuples: number;
-  inputPortShapes?: { portIndex: number; rows: number; columns: number }[];
-  outputColumns?: number;
-  error?: string;
-  warnings?: string[];
-  consoleLogCount?: number;
-  totalRowCount?: number;
-  sampleRecords?: Record<string, any>[];
-  resultStatistics?: Record<string, string>;
-}
-
-interface WsOutgoingMessage {
-  type: "step" | "state" | "error" | "complete" | "init" | "headChange";
-  step?: ReActStep;
-  state?: string;
-  error?: string;
-  steps?: ReActStep[];
-  headId?: string;
-  operatorResults?: Record<string, OperatorResultSummaryWs>;
-  workflowContent?: any;
-}
-
 function getOperatorResultSummaries(agent: TexeraAgent): Record<string, OperatorResultSummaryWs> {
   const resultState = agent.getWorkflowResultState();
   const visible = resultState.getAllVisible();
@@ -464,7 +434,7 @@ function getOperatorResultSummaries(agent: TexeraAgent): Record<string, Operator
   return results;
 }
 
-function broadcastToAgent(agentId: string, message: WsOutgoingMessage): void {
+function broadcastToAgent(agentId: string, message: WsServerMessage): void {
   const agent = agentStore.get(agentId);
   if (!agent) return;
 
@@ -504,7 +474,7 @@ export function buildApp() {
 
         agent.addWebsocket(ws);
 
-        const initMessage: WsOutgoingMessage = {
+        const initMessage: WsServerInitMessage = {
           type: "init",
           state: agent.getState(),
           steps: agent.getAllSteps(),
@@ -523,21 +493,23 @@ export function buildApp() {
           return;
         }
 
-        let msg: WsMessage;
+        let msg: WsClientRequest;
         try {
-          msg = typeof messageData === "string" ? JSON.parse(messageData) : (messageData as WsMessage);
+          msg = typeof messageData === "string" ? JSON.parse(messageData) : (messageData as WsClientRequest);
         } catch {
           ws.send(JSON.stringify({ type: "error", error: "Invalid message format" }));
           return;
         }
 
-        if (msg.type === "stop") {
-          agent.stop();
-          broadcastToAgent(agentId, { type: "state", state: "STOPPING" });
+        if (msg.type === "command") {
+          if (msg.commandType === "stop") {
+            agent.stop();
+            broadcastToAgent(agentId, { type: "state", state: AgentState.STOPPING });
+          }
           return;
         }
 
-        if (msg.type === "message") {
+        if (msg.type === "prompt") {
           if (!msg.content || typeof msg.content !== "string") {
             ws.send(JSON.stringify({ type: "error", error: "Message content is required" }));
             return;
@@ -554,7 +526,7 @@ export function buildApp() {
             });
           });
 
-          broadcastToAgent(agentId, { type: "state", state: "GENERATING" });
+          broadcastToAgent(agentId, { type: "state", state: AgentState.GENERATING });
 
           try {
             const result = await agent.sendMessage(msg.content, msg.messageSource);
@@ -630,9 +602,9 @@ function printStartupMessage(app: ReturnType<typeof buildApp>) {
     for (const route of wsRoutes) {
       console.log(`  WS     ${route.path}`);
     }
-    console.log("         Send: { type: 'message', content: '...' }");
-    console.log("         Send: { type: 'stop' }");
-    console.log("         Recv: { type: 'step' | 'state' | 'complete' | 'error' | 'init', ... }");
+    console.log("         Send: { type: 'prompt', content: '...' }");
+    console.log("         Send: { type: 'command', commandType: 'stop' }");
+    console.log("         Recv: { type: 'step' | 'state' | 'complete' | 'error' | 'init' | 'headChange', ... }");
   }
 
   console.log("");

agent-service/src/types/index.ts

@@ -20,3 +20,4 @@
 export * from "./workflow";
 export * from "./execution";
 export * from "./agent";
+export * from "./ws";

agent-service/src/types/ws/client.ts

@@ -0,0 +1,43 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Client -> server WebSocket frames for this service's protocol
+// (/agents/:id/react). Modeled as a discriminated union on `type` so each
+// request kind carries only its own fields, rather than one interface with
+// everything optional.
+
+interface WsClientRequestBase {
+  type: "prompt" | "command";
+}
+
+// A user prompt to run through the agent.
+export interface WsClientRequestPrompt extends WsClientRequestBase {
+  type: "prompt";
+  content: string;
+  messageSource?: "chat" | "feedback";
+}
+
+// A control command. Today the only command stops the in-flight run; the
+// `commandType` discriminator leaves room for additional commands later.
+export interface WsClientRequestStopCommand extends WsClientRequestBase {
+  type: "command";
+  commandType: "stop";
+}
+
+export type WsClientRequest = WsClientRequestPrompt | WsClientRequestStopCommand;

agent-service/src/types/ws/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// WebSocket frames for this service's own protocol (/agents/:id/react):
+// inbound client requests and the outbound server messages it pushes back.
+
+export * from "./client";
+export * from "./server";

agent-service/src/types/ws/server.ts

@@ -0,0 +1,101 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Server -> client WebSocket frames for this service's protocol
+// (/agents/:id/react). Modeled as a discriminated union on `type` so each
+// message kind declares exactly the fields it sends.
+
+import type { AgentState, ReActStep } from "../agent";
+import type { WorkflowContent } from "../workflow";
+
+// Wire projection of an operator's execution result, summarized for the client
+// (counts instead of full payloads; only a sample of records).
+export interface OperatorResultSummaryWs {
+  state: string;
+  inputTuples: number;
+  outputTuples: number;
+  inputPortShapes?: { portIndex: number; rows: number; columns: number }[];
+  outputColumns?: number;
+  error?: string;
+  warnings?: string[];
+  consoleLogCount?: number;
+  totalRowCount?: number;
+  sampleRecords?: Record<string, unknown>[];
+  resultStatistics?: Record<string, string>;
+}
+
+type OperatorResults = Record<string, OperatorResultSummaryWs>;
+
+interface WsServerMessageBase {
+  type: "init" | "step" | "state" | "complete" | "error" | "headChange";
+}
+
+// Sent once on connect: a snapshot of the agent's current state and steps.
+export interface WsServerInitMessage extends WsServerMessageBase {
+  type: "init";
+  state: AgentState;
+  steps: ReActStep[];
+  headId: string;
+  operatorResults: OperatorResults;
+}
+
+// A single ReAct step streamed as the agent runs. Operator results accompany
+// steps that ran tools.
+export interface WsServerStepMessage extends WsServerMessageBase {
+  type: "step";
+  step: ReActStep;
+  operatorResults?: OperatorResults;
+}
+
+// An agent lifecycle transition (e.g. GENERATING, STOPPING).
+export interface WsServerStateMessage extends WsServerMessageBase {
+  type: "state";
+  state: AgentState;
+}
+
+// Terminal message for a finished run.
+export interface WsServerCompleteMessage extends WsServerMessageBase {
+  type: "complete";
+  state: AgentState;
+  operatorResults: OperatorResults;
+}
+
+// An error surfaced to the client.
+export interface WsServerErrorMessage extends WsServerMessageBase {
+  type: "error";
+  error: string;
+}
+
+// Emitted after a checkout: the head moved, carrying the full step list and the
+// workflow snapshot at the new head.
+export interface WsServerHeadChangeMessage extends WsServerMessageBase {
+  type: "headChange";
+  headId: string;
+  steps: ReActStep[];
+  workflowContent?: WorkflowContent;
+  operatorResults: OperatorResults;
+}
+
+export type WsServerMessage =
+  | WsServerInitMessage
+  | WsServerStepMessage
+  | WsServerStateMessage
+  | WsServerCompleteMessage
+  | WsServerErrorMessage
+  | WsServerHeadChangeMessage;

frontend/src/app/workspace/service/agent/agent.service.ts

@@ -909,7 +909,7 @@ export class AgentService {
     }
 
     const wsMessage = {
-      type: "message",
+      type: "prompt",
       content: message,
       messageSource,
     };
@@ -967,7 +967,7 @@ export class AgentService {
     if (tracking?.websocket && tracking.websocket.readyState === WebSocket.OPEN) {
       // Send stop via WebSocket for immediate effect
       try {
-        tracking.websocket.send(JSON.stringify({ type: "stop" }));
+        tracking.websocket.send(JSON.stringify({ type: "command", commandType: "stop" }));
       } catch (error) {
         console.error("Failed to send stop command:", error);
       }