@j-o-r/hello-dave 0.0.5 → 0.0.7

package/lib/AgentServer.js

@@ -4,65 +4,76 @@ const TIMEOUT = 30000;
 const MAX_INTERVALS = 20; // 10 minutes (30 sec * 20) 
 
 let ws;
+
+/**
+ * @module lib/AgentServer
+ * @exports default AgentServer
+ * Dynamic WebSocket server for AI agents. Registers connected clients as dynamic tool calls in the Prompt's ToolSet.
+ * Handles authentication, user/agent messages, sessions, resets, and broadcasts.
+ */
+
 /**
-@typedef  {import('../node_modules/@j-o-r/apiserver/types/ClientWrapper.d.ts').ClientWrapper} Client 
-@typedef {import('./Prompt.js').default} Prompt
-@typedef {import('./ToolSet.js').default} ToolSet
-@typedef {import('./Session.js').default} Session
-*/
+ * @typedef {import('@j-o-r/apiserver/types/ClientWrapper.d.ts').ClientWrapper} Client 
+ * @typedef {import('./Prompt.js').default} Prompt
+ * @typedef {import('./ToolSet.js').default} ToolSet
+ * @typedef {import('./Session.js').default} Session
+ */
 /**
-* @type {string|object} messageContent
-*/
+ * @typedef {string|object} MessageContent
+ */
 /**
-* @type {Object} message
-* @property {string} action
-* @property {messageContent} content
-*/
+ * @typedef {Object} Message
+ * @property {string} action - Action type (must be in ACTIONS).
+ * @property {MessageContent} [content]
+ * @property {string} [id]
+ */
 /**
-* @typedef {(conn: import('@j-o-r/apiserver/types/WebSocketServer.js').WebSocketConnection, req: any) => Promise<boolean>} AuthFunction
-*/
+ * @typedef {(conn: import('@j-o-r/apiserver/types/WebSocketServer.js').WebSocketConnection, req: any) => Promise&lt;boolean&gt;} AuthFunction
+ */
 /**
-* @typedef {Object} AgentServerOptions
-* @property {string} name
-* @property {string} secret - server access secret
-* @property {string} description
-* @property {Prompt} prompt
-* @property {Session} session
-* @property {AuthFunction} [auth]
-* @property {number} [port] - default 8000
-* @property {boolean} [debug = false] 
-*/
+ * @typedef {Object} AgentServerOptions
+ * @property {string} name - Server/agent name.
+ * @property {string} secret - Access secret (matches client secrets).
+ * @property {string} description - Server description.
+ * @property {Prompt} prompt - Prompt instance.
+ * @property {Session} session - Session manager.
+ * @property {AuthFunction} [auth] - Custom auth function.
+ * @property {number} [port=8000] - Listen port (&gt;=1024).
+ * @property {boolean} [debug=false] - Verbose logging.
+ * @example { name: 'main-agent', prompt: myPrompt, session: mySession, secret: 'abc', port: 8001 }
+ */
 
+/** @const @type {readonly string[]} Supported WebSocket message actions. Use .includes() for validation. */
 const ACTIONS = [
 	// Agent / Toolset function calls
-	'agent_introduction', // Describe your task, your purpose and usage. This is a reaction on a 'introduce' requests
-	'agent_error',        // Message error
-	'agent_query',        // doing a query
-	'agent_response',     // Doing an response on a query
-	// Regular user interaction
-	'user_introduction',  // Websocket client connection on open
-	'user_request',       // A client user request
-	'server_response',    // A reponse to a user request
-	'server_error',    // A reponse to a user request
-	'user_reset',         // User requests a new session
-	'user_sessionlist',   // Request a list of sessions
-	'user_loadsession',   // Request to load a session
-	'user_info',          // User request server info
+	'agent_introduction', // Client introduces as tool
+	'agent_error',        // Agent error response
+	'agent_query',        // Query to agent
+	'agent_response',     // Agent response
+	// User interactions
+	'user_introduction',  // Client connect
+	'user_request',       // User query
+	'server_response',    // Server response to user
+	'server_error',       // Server error to user
+	'user_reset',         // Reset session
+	'user_sessionlist',   // List sessions
+	'user_loadsession',   // Load session
+	'user_info',          // Server info
 ];
 
-
-
-
-// WS clients 
+// WS clients map: conn_id → agent name
 const clients = new Map();
-// Pending  messages
-const pendingResponses = new Map(); // key: `${conn_id}:${msg_id}`, value: {resolve, reject}
+// Pending responses: `${conn_id}:${msg_id}` → {resolve, reject, timer}
+const pendingResponses = new Map();
 
 /**
-* Delete a client from the toolset
-* @param {ToolSet|void} toolset
-* @param {string} conn_id - Connection id
-*/
+ * @function deleteClient
+ * @private
+ * Removes a client from the toolset and clients map.
+ * @param {ToolSet|null} toolset - Prompt's toolset.
+ * @param {string} conn_id - Connection ID.
+ * @returns {void}
+ */
 const deleteClient = (toolset, conn_id) => {
 	if (!toolset) return;
 	const name = clients.get(conn_id);
@@ -72,13 +83,19 @@ const deleteClient = (toolset, conn_id) => {
 			toolset.delete(name);
 		}
 	}
-}
+};
+
 /**
-* @param {ToolSet|void} toolset
-* @param {string} conn_id - Connection id
-* @param {string} name - logical name / task
-* @param {string} description of the logical name
-*/
+ * @function addClient
+ * @private
+ * Registers a WS client as a dynamic tool in the toolset.
+ * Sends query via WS, awaits response with timeout.
+ * @param {ToolSet|null} toolset - Prompt's toolset.
+ * @param {string} conn_id - Connection ID.
+ * @param {string} name - Tool name.
+ * @param {string} description - Tool description.
+ * @returns {void}
+ */
 const addClient = (toolset, conn_id, name, description) => {
 	if (!toolset) return;
 	toolset.add(
@@ -89,7 +106,7 @@ const addClient = (toolset, conn_id, name, description) => {
 			properties: {
 				query: {
 					type: 'string',
-					description: `Command, question or query for this particulair expert well formed in natural language`
+					description: `Command, question or query for this particular expert well formed in natural language`
 				}
 			},
 			required: ['query']
@@ -101,7 +118,6 @@ const addClient = (toolset, conn_id, name, description) => {
 				const key = `${conn_id}:${msg_id}`;
 				clients.set(conn_id, name);
 
-				// Start timeout/interval and keep its handle so we can clear it on response
 				let intervals = 0;
 				const timer = setInterval(() => {
 					intervals++;
@@ -114,7 +130,6 @@ const addClient = (toolset, conn_id, name, description) => {
 					}
 				}, TIMEOUT);
 
-				// Store handlers and timer so onMessage can resolve/reject and clear the timer
 				pendingResponses.set(key, { resolve, reject, timer });
 
 				ws.sendToConnection(conn_id, JSON.stringify({
@@ -122,34 +137,66 @@ const addClient = (toolset, conn_id, name, description) => {
 					id: msg_id,
 					content: params.query
 				}));
-			}).then(response => (response));
-		})
-}
+			});
+		}
+	);
+};
 
-// Provide a toolset based on websocket calls
+/**
+ * AgentServer: Core WebSocket server class.
+ * Exposes connected agents as tools; handles user CLI/WS interactions, auth, sessions.
+ * Starts on localhost; broadcasts resets.
+ * Logs events via console; emits via Prompt.
+ * @emits tool_request - Tool calls (via #prompt).
+ * @emits tool_error - Tool failures (via #prompt).
+ * @example
+ * const server = new AgentServer({
+ *   name: 'main',
+ *   prompt: myPrompt,
+ *   session: mySession,
+ *   secret: 'abc',
+ *   port: 8000,
+ *   debug: true
+ * });
+ */
 class AgentServer {
+	/** @private @type {boolean} */
 	#debug = false;
+	/** @private @type {number} */
 	#port = 8000;
+	/** @private @type {string} */
 	#name = '';
-	#secret = ''; // access secret
+	/** @private @type {string} */
+	#secret = '';
+	/** @private @type {string} */
 	#description = '';
-	/** @type {Prompt} */
-	#prompt
-	/** @type {Session} */
-	#session
-	/** @type {AuthFunction} */
+	/** @private @type {Prompt} */
+	#prompt;
+	/** @private @type {Session} */
+	#session;
+	/**
+	 * @private
+	 * Default auth: Checks 'wssrc_id' query param against #secret.
+	 * @param {Object} conn - Connection object.
+	 * @returns {Promise&lt;boolean&gt;}
+	 */
 	#auth = async (conn) => {
 		const q = conn.client.query;
 		const key = q.get('wssrc_id');
 		return key === this.#secret;
-	}
+	};
+
 	/**
-	* @param {AgentServerOptions} options
-	*/
+	 * Initializes and starts the AgentServer.
+	 * Validates port, sets up Prompt event logging, launches WS server.
+	 * @param {AgentServerOptions} options - Server configuration.
+	 * @throws {Error} If port &lt; 1024.
+	 * @example See AgentServerOptions.
+	 */
 	constructor(options) {
 		if (options.port) {
 			if (options.port < 1024) {
-				throw new Error('Port must be higher then 1024');
+				throw new Error('Port must be higher than 1024');
 			}
 			this.#port = options.port;
 		}
@@ -161,12 +208,12 @@ class AgentServer {
 		this.#description = options.description;
 		this.#session = options.session;
 		this.#prompt = options.prompt;
-		this.#debug = options.debug;
-		// LOG EVENTS
+		this.#debug = options.debug ?? false;
+
+		// Log Prompt events
 		const events = Object.keys(this.#prompt.EVENTS);
 		events.forEach((evt) => {
 			this.#prompt.on(evt, (_msg) => {
-				// log events
 				console.log(`** ${this.#name} e:${evt}**`);
 				if (evt === 'tool_request') {
 					console.log(`tool execute: ${this.#name} ${_msg.name} ${_msg.call_id}`);
@@ -176,18 +223,19 @@ class AgentServer {
 				}
 			});
 		});
-		// start 
+
+		// Async start
 		(async () => {
 			await this._start();
 		})();
 	}
+
 	/**
-	* @private
-	* Returns a Dynamic Toolset
-	* With registered WS clients as toolcalls
-	* A deamon start on local host 127.0.0.1, always
-	* @returns {Promise<void>}
-	*/
+	 * @private
+	 * Launches the WS server with handlers for messages, connections, closes.
+	 * Defines HTTP / API index endpoint.
+	 * @returns {Promise&lt;void&gt;}
+	 */
 	async _start() {
 		const name = this.#name;
 		const description = this.#description;
@@ -195,8 +243,8 @@ class AgentServer {
 		const DEBUG = this.#debug;
 		const API = {
 			/**
-			* @param {Client} client
-			*/
+			 * @param {Client} client
+			 */
 			index: async (client) => {
 				await client.serve(200, { name, description });
 			}
@@ -205,18 +253,16 @@ class AgentServer {
 			verbose: this.#debug,
 			onMessage: async (conn, msg) => {
 				if (!msg.action || !ACTIONS.includes(msg.action)) {
-					console.log('Unkown action: ' + msg.action);
-					deleteClient(this.#prompt.toolset, conn.id)
+					console.log('Unknown action: ' + msg.action);
+					deleteClient(this.#prompt.toolset, conn.id);
 					ws.closeConnection(conn.id);
 					return;
 				}
 				if (msg.action === 'agent_introduction') {
-					// Register Toolset Agent
-					// CLient is added as a Toolset function call
 					const name = msg.name;
 					const content = (typeof msg.content === 'string') ? msg.content : JSON.stringify(msg.content);
 					if (!content) {
-						deleteClient(this.#prompt.toolset, conn.id)
+						deleteClient(this.#prompt.toolset, conn.id);
 						ws.closeConnection(conn.id);
 						return;
 					}
@@ -224,7 +270,7 @@ class AgentServer {
 					return;
 				}
 				if (msg.action === 'agent_response') {
-					const key = `${conn.id}:${msg.id}`; // Assume client includes original 'id' in response
+					const key = `${conn.id}:${msg.id}`;
 					const pending = pendingResponses.get(key);
 					if (pending) {
 						try { clearInterval(pending.timer); } catch { }
@@ -234,7 +280,7 @@ class AgentServer {
 					return;
 				}
 				if (msg.action === 'agent_error') {
-					const key = `${conn.id}:${msg.id}`; // Assume client includes original 'id' in response
+					const key = `${conn.id}:${msg.id}`;
 					const pending = pendingResponses.get(key);
 					if (pending) {
 						try { clearInterval(pending.timer); } catch { }
@@ -243,21 +289,17 @@ class AgentServer {
 					}
 					return;
 				}
-				// -------- USER INTERACTION --------------------------------------------------------
-				// CLI / WS interaction to MAIN
+				// User interactions
 				if (msg.action === 'user_request') {
-					const action = `user_reponse`;
 					const id = msg.id;
 					if (!msg.content || msg.content.trim() === '') {
-						// Empty message, empty reponse
 						ws.sendToConnection(conn.id, JSON.stringify({
-							action: 'user_response',
+							action: 'server_response',
 							id,
 							content: ''
 						}));
 						return;
 					}
-					// Bind to THIS prompt
 					console.log(`user_request:>>\n${msg.content}\n`);
 					try {
 						const content = await this.#prompt.call(msg.content);
@@ -266,14 +308,14 @@ class AgentServer {
 							id,
 							content
 						}));
-						console.log(`server_reponse:>>\n${content}\n`);
+						console.log(`server_response:>>\n${content}\n`);
 					} catch (e) {
 						console.log(`server_error:>>\n`);
 						console.error(e);
 						ws.sendToConnection(conn.id, JSON.stringify({
 							action: 'server_error',
 							id,
-							e
+							e: String(e)
 						}));
 					}
 				}
@@ -296,7 +338,6 @@ class AgentServer {
 						content: sess
 					}));
 				}
-
 				if (msg.action === 'user_loadsession') {
 					const id = msg.id;
 					const selected = msg.content;
@@ -315,8 +356,7 @@ class AgentServer {
 								}
 							}
 						}
-					};
-					// Resume execution
+					}
 					await this.#prompt.triggerRequest();
 					ws.sendToConnection(conn.id, JSON.stringify({
 						action: 'server_sessionloaded',
@@ -341,10 +381,8 @@ class AgentServer {
 			},
 			onClose: async (conn, reason) => {
 				deleteClient(this.#prompt.toolset, conn.id);
-
 			},
 			onError: async (conn, error) => {
-				// console.error(error);
 				deleteClient(this.#prompt.toolset, conn.id);
 				ws.closeConnection(conn.id);
 			}
@@ -352,10 +390,12 @@ class AgentServer {
 		await server.create('v1', { port, host: '127.0.0.1', ws, strict: DEBUG, verbose: DEBUG }, API);
 		console.log(`Websocket server: ws://127.0.0.1:${port}/ws`);
 	}
+
 	/**
-	* Send a reset messages to all clients
-	* reset will start a new session
-	*/
+	 * Broadcasts a reset message to all connected clients (starts new sessions).
+	 * @returns {void}
+	 * @fires reset - Via underlying prompt/clients.
+	 */
 	resetAll() {
 		ws.broadcast({ action: 'reset' });
 	}