@j-o-r/hello-dave 0.1.0 → 0.1.4

package/lib/AgentManager.js

@@ -1,245 +0,0 @@
-import { Prompt, Cli, AgentClient, AgentServer, API, ToolSet, Session, env } from './index.js';
-import toolsPool from './genericToolset.js'
-/**
- * @module lib/AgentManager
- * @exports default AgentManager
- * High-level orchestrator for AI agent lifecycle: configures Prompt/Session/ToolSet, launches CLI/Server/Client modes.
- * Supports chaining setup() → start(); adds generic tools; direct calls.
- */
-
-/**
- * @typedef {import('./API/x.ai/text.js').XOptions} XOptions
- * @typedef {import('./API/x.ai/responses.js').XAIOptions} XAIOptions
- * @typedef {import('./API/openai.com/reponses/text.js').OAOptions} OAOptions
- * @typedef {import('./API/anthropic.com/text.js').ANTHOptions} ANTHOptions
- */
-/**
- * @typedef {Object} Setup
- * @property {string} prompt - Initial system prompt.
- * @property {XAIOptions|OAOptions|XOptions|ANTHOptions} options - API model options.
- * @property {'gpt'|'xai'|'claude'} api - AI provider.
- * @property {number} [contextWindow=300000] - Token limit for context.
- * @property {'auto'|'required'|null} [toolsetMode] - Toolset activation mode.
- * @property {boolean} [debug] - Enable verbose output.
- */
-/**
- * @typedef {Object} Options
- * @property {string} name - Agent name (validated /^[a-z_0-9]{2,}$/).
- * @property {string} secret - WS auth secret (base64-encoded).
- * @property {string} [cachePath='.cache/hello-dave'] - Session cache directory.
- * @example { name: 'code-agent', secret: 'mysecret' }
- */
-/** @const {RegExp} Validates agent/tool names (lowercase a-z0-9_, min 2 chars). */
-const validNameRegex = /^[a-z_0-9]{2,}$/;
-
-class AgentManager {
-	/** @private @type {Prompt} */
-  #prompt;
-  /** @private @type {Session} */
-  #sessionStorage;
-  /** @private @type {string} */
-  #name = 'agent';
-  /** @private @type {string} */
-  #secret = '';
-  /** @private @type {string} */
-  #cachePath = '.cache/hello-dave';
-  /** @private @type {boolean} */
-  #debug = false;
-  /** @private @type {string} */
-  #model = '';
-  /** @private @type {number} */
-  #contextWindow = 0;
-  /** @private @type {string} */
-  #sysPrompt = '';
-
-  /**
-   * Initializes AgentManager with base options.
-   * Validates name regex; encodes secret.
-   * @param {Options} options - Base configuration.
-   * @throws {Error} Invalid name (regex) or options.
-   * @chainable
-   */
-  constructor(options) {
-    this.#name = options.name || this.#name;
-    if (options.secret && typeof options.secret === 'string') {
-      this.#secret = Buffer.from(options.secret).toString('base64');
-    } 
-    if (!validNameRegex.test(this.#name)) {
-      throw new Error(`Invalid agent 'name': '${this.#name}'. Must match /^[a-z_0-9]{2,}$/`);
-    }
-    this.#cachePath = options.cachePath || this.#cachePath;
-  }
-
-  /**
-   * Configures the Prompt/Session/ToolSet with API adaptor.
-   * Adds system prompt; chains to start().
-   * @param {Setup} setup - AI setup details.
-   * @returns {AgentManager} This instance (chainable).
-   * @throws {Error} Invalid setup.
-   * @example mgr.setup({ prompt: 'You are a coder...', api: 'gpt', options: { model: 'gpt-4o' } });
-   */
-  setup(setup) {
-    const {
-    	prompt,
-    	api = 'gpt',
-    	contextWindow = 300000,
-    	options = null,
-    	toolsetMode = null,
-    	debug = false
-    } = setup;
-    this.#sysPrompt = prompt;
-    this.#contextWindow = contextWindow;
-    if (options?.model) this.#model = options.model;
-    let toolset;
-    if (toolsetMode) {
-    	toolset = new ToolSet(toolsetMode);
-    }
-    if (debug) {
-    	this.#debug = true;
-    }
-    this.#prompt = new Prompt(contextWindow);
-    this.#sessionStorage = new Session(this.#name, this.#prompt, this.#cachePath);
-    this.#prompt.add('system', prompt, true);
-    this.#prompt.setAdaptor(API.text[api], toolset, options);
-    return this;
-  }
-
-  /**
-   * @private
-   * Launches interactive CLI mode.
-   * @param {string} description - CLI intro message.
-   * @returns {void}
-   * @throws {Error} No setup() called.
-   */
-  #startCli(description) {
-    if (!this.#prompt) throw new Error('Run setup first');
-    const cli = new Cli({ prompt: this.#prompt, session: this.#sessionStorage, description });
-    setTimeout(() => {
-      cli.start();
-    }, 1000);
-  }
-
-  /**
-   * @private
-   * Attaches this agent as a WS client to another server (for chaining agents).
-   * @param {string} name - Tool name.
-   * @param {string} description - Tool desc.
-   * @param {string} [url='ws://127.0.0.1:8000/ws'] - Target WS URL.
-   * @returns {AgentClient} New client instance.
-   * @throws {Error} No setup().
-   */
-  #attach(name, description, url = 'ws://127.0.0.1:8000/ws') {
-    if (!this.#prompt) throw new Error('Run setup first');
-    return new AgentClient({ prompt: this.#prompt, name, description, url, secret: this.#secret });
-  }
-
-  /**
-   * @private
-   * Enables server mode: Registers this agent for remote tool calls.
-   * Optionally attaches as client too.
-   * @param {string} name - Server/tool name.
-   * @param {string} [description=''] - Desc (auto from sysPrompt).
-   * @param {number} [port=8000] - Port.
-   * @returns {void}
-   * @throws {Error} No setup/toolset.
-   */
-  #enableServer(name, description = '', port = 8000) {
-    if (!this.#prompt) throw new Error('Run setup first');
-    if (!this.#prompt.toolset) throw new Error('No toolset defined');
-    const server = new AgentServer({
-    	port,
-    	name,
-    	secret: this.#secret,
-    	description,
-    	prompt: this.#prompt,
-    	session: this.#sessionStorage,
-    	debug: this.#debug
-    });
-    this.#prompt.on('reset', () => {
-    	server.resetAll();
-    });
-  }
-
-  /**
-   * Direct synchronous call to the underlying Prompt.
-   * @param {string} input - User input.
-   * @returns {Promise<string>} Response.
-   * @throws {Error} No setup.
-   */
-  async directCall(input) {
-		const res = await this.#prompt.call(input);
-  	return res;
-  }
-
-  /** @returns {Prompt} Underlying Prompt instance. */
-  getPrompt() { return this.#prompt; }
-
-  /** @returns {ToolSet|null} Toolset if configured. */
-  getToolset() { return this.#prompt.toolset; }
-
-  /** @returns {Promise<import('./fafs.js').EnvironmentInfo>} System env info. */
-  async environment() {
-  	return env();
-  }
-
-  /**
-   * Adds a pre-defined generic tool from toolsPool (genericToolset) to this agent's ToolSet.
-   * @param {'execute_bash_script'|'execute_remote_script'|'get_user_env'|'history_search'|'javascript_interpreter'|'memory_recall'|'memory_write'|'open_link'|'read_file'|'send_email'|'syntax_check'|'write_file'} name - Tool name.
-   * @throws {Error} Invalid name, no toolset, or tool missing.
-   * @example mgr.addGenericToolcall('read_file');
-   */
-  addGenericToolcall(name) {
-    if (!validNameRegex.test(name)) {
-      throw new Error(`Invalid 'name': '${name}'. Must match /^[a-z_0-9]{2,}$/`);
-    }
-    if (!this.#prompt.toolset) throw new Error('No ToolSet defined');
-    let tool = toolsPool.get(name);
-    if (!tool) throw new Error(`Tool '${name}' not found in pool`);
-    this.#prompt.toolset.add(name, tool.description, tool.parameters, tool.method);
-  }
-  
-  /**
-   * Smart launcher: CLI (default), server (servePort), or client (connectUrl).
-   * Auto-generates intros/descriptions if empty.
-   * @param {number} [servePort] - Launch server on port.
-   * @param {string} [connectUrl] - Connect as client to WS.
-   * @param {string} [cliIntro=""] - CLI intro text.
-   * @param {string} [toolName=""] - Tool/server name (falls back to #name).
-   * @param {string} [toolDescription=""] - Tool desc.
-   * @returns {Promise<void>}
-   * @throws {Error} No setup; invalid names/ports.
-   * @example mgr.start(8000); // Server\nmgr.start(undefined, 'ws://other:8001/ws'); // Client\nmgr.start(); // CLI
-   */
-  async start(servePort, connectUrl, cliIntro = "", toolName = "", toolDescription = "") {
-    if (!this.#prompt) throw new Error("Run setup first");
-
-    toolName = toolName || this.#name;
-    if (!validNameRegex.test(toolName)) {
-      throw new Error(`Invalid 'toolName': '${toolName}'. Must match /^[a-z_0-9]{2,}$/`);
-    }
-
-    if (!toolDescription && this.#sysPrompt) {
-      toolDescription = this.#sysPrompt.slice(0, 100).trim() + "...";
-    }
-
-    if (!cliIntro) {
-      const introStr = `${this.#name} ${this.#model || "unknown-model"} - context: ${this.#contextWindow}`;
-      cliIntro = introStr.trim();
-    }
-
-    if (servePort) {
-      console.log(toolName);
-      console.log(toolDescription);
-      this.#enableServer(toolName, toolDescription, servePort);
-      if (connectUrl) {
-        this.#attach(toolName, toolDescription, connectUrl);
-      }
-    } else if (connectUrl) {
-      this.#attach(toolName, toolDescription, connectUrl);
-    } else {
-      this.#startCli(cliIntro);
-    }
-  }
-}
-
-export default AgentManager;

package/lib/AgentServer.js

@@ -1,404 +0,0 @@
-import { WebSocketServer, server } from '@j-o-r/apiserver';
-
-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('@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 {string|object} MessageContent
- */
-/**
- * @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 {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 (>=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', // 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 map: conn_id → agent name
-const clients = new Map();
-// Pending responses: `${conn_id}:${msg_id}` → {resolve, reject, timer}
-const pendingResponses = new Map();
-
-/**
- * @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);
-	if (name) {
-		clients.delete(conn_id);
-		if (toolset.has(name)) {
-			toolset.delete(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(
-		name,
-		description,
-		{
-			type: 'object',
-			properties: {
-				query: {
-					type: 'string',
-					description: `Command, question or query for this particular expert well formed in natural language`
-				}
-			},
-			required: ['query']
-		},
-		// @ts-ignore
-		(params) => {
-			return new Promise((resolve, reject) => {
-				const msg_id = Date.now().toString();
-				const key = `${conn_id}:${msg_id}`;
-				clients.set(conn_id, name);
-
-				let intervals = 0;
-				const timer = setInterval(() => {
-					intervals++;
-					if (intervals >= MAX_INTERVALS) {
-						clearInterval(timer);
-						if (pendingResponses.has(key)) {
-							reject('Timeout after max intervals');
-							pendingResponses.delete(key);
-						}
-					}
-				}, TIMEOUT);
-
-				pendingResponses.set(key, { resolve, reject, timer });
-
-				ws.sendToConnection(conn_id, JSON.stringify({
-					action: 'agent_query',
-					id: msg_id,
-					content: params.query
-				}));
-			});
-		}
-	);
-};
-
-/**
- * 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 = '';
-	/** @private @type {string} */
-	#secret = '';
-	/** @private @type {string} */
-	#description = '';
-	/** @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<boolean>}
-	 */
-	#auth = async (conn) => {
-		const q = conn.client.query;
-		const key = q.get('wssrc_id');
-		return key === this.#secret;
-	};
-
-	/**
-	 * Initializes and starts the AgentServer.
-	 * Validates port, sets up Prompt event logging, launches WS server.
-	 * @param {AgentServerOptions} options - Server configuration.
-	 * @throws {Error} If port < 1024.
-	 * @example See AgentServerOptions.
-	 */
-	constructor(options) {
-		if (options.port) {
-			if (options.port < 1024) {
-				throw new Error('Port must be higher than 1024');
-			}
-			this.#port = options.port;
-		}
-		if (options.auth) {
-			this.#auth = options.auth;
-		}
-		this.#name = options.name;
-		this.#secret = options.secret;
-		this.#description = options.description;
-		this.#session = options.session;
-		this.#prompt = options.prompt;
-		this.#debug = options.debug ?? false;
-
-		// Log Prompt events
-		const events = Object.keys(this.#prompt.EVENTS);
-		events.forEach((evt) => {
-			this.#prompt.on(evt, (_msg) => {
-				console.log(`** ${this.#name} e:${evt}**`);
-				if (evt === 'tool_request') {
-					console.log(`tool execute: ${this.#name} ${_msg.name} ${_msg.call_id}`);
-				} else if (evt === 'tool_error') {
-					console.log(`tool error:`);
-					console.log(JSON.stringify(_msg, null, '  '));
-				}
-			});
-		});
-
-		// Async start
-		(async () => {
-			await this._start();
-		})();
-	}
-
-	/**
-	 * @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;
-		const port = this.#port;
-		const DEBUG = this.#debug;
-		const API = {
-			/**
-			 * @param {Client} client
-			 */
-			index: async (client) => {
-				await client.serve(200, { name, description });
-			}
-		};
-		ws = new WebSocketServer({
-			verbose: this.#debug,
-			onMessage: async (conn, msg) => {
-				if (!msg.action || !ACTIONS.includes(msg.action)) {
-					console.log('Unknown action: ' + msg.action);
-					deleteClient(this.#prompt.toolset, conn.id);
-					ws.closeConnection(conn.id);
-					return;
-				}
-				if (msg.action === 'agent_introduction') {
-					const name = msg.name;
-					const content = (typeof msg.content === 'string') ? msg.content : JSON.stringify(msg.content);
-					if (!content) {
-						deleteClient(this.#prompt.toolset, conn.id);
-						ws.closeConnection(conn.id);
-						return;
-					}
-					addClient(this.#prompt.toolset, conn.id, name, content);
-					return;
-				}
-				if (msg.action === 'agent_response') {
-					const key = `${conn.id}:${msg.id}`;
-					const pending = pendingResponses.get(key);
-					if (pending) {
-						try { clearInterval(pending.timer); } catch { }
-						pending.resolve(msg.content);
-						pendingResponses.delete(key);
-					}
-					return;
-				}
-				if (msg.action === 'agent_error') {
-					const key = `${conn.id}:${msg.id}`;
-					const pending = pendingResponses.get(key);
-					if (pending) {
-						try { clearInterval(pending.timer); } catch { }
-						pending.reject(msg.content);
-						pendingResponses.delete(key);
-					}
-					return;
-				}
-				// User interactions
-				if (msg.action === 'user_request') {
-					const id = msg.id;
-					if (!msg.content || msg.content.trim() === '') {
-						ws.sendToConnection(conn.id, JSON.stringify({
-							action: 'server_response',
-							id,
-							content: ''
-						}));
-						return;
-					}
-					console.log(`user_request:>>\n${msg.content}\n`);
-					try {
-						const content = await this.#prompt.call(msg.content);
-						ws.sendToConnection(conn.id, JSON.stringify({
-							action: 'server_response',
-							id,
-							content
-						}));
-						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: String(e)
-						}));
-					}
-				}
-				if (msg.action === 'user_reset') {
-					const id = msg.id;
-					this.#prompt.reset();
-					ws.sendToConnection(conn.id, JSON.stringify({
-						action: 'server_reset',
-						id,
-						content: 'ok'
-					}));
-				}
-				if (msg.action === 'user_sessionlist') {
-					const id = msg.id;
-					const sess = this.#session.sessionList().reverse();
-					sess.push('NONE');
-					ws.sendToConnection(conn.id, JSON.stringify({
-						action: 'server_sessionlist',
-						id,
-						content: sess
-					}));
-				}
-				if (msg.action === 'user_loadsession') {
-					const id = msg.id;
-					const selected = msg.content;
-					const messages = [];
-					const list = this.#session.set(selected);
-					this.#prompt.messages = list;
-					let i = 0;
-					const length = list.length;
-					for (; i < length; i++) {
-						const msg = list[i];
-						if (!msg.sticky) {
-							if (['user', 'assistant', 'reasoning', 'log'].includes(msg.role)) {
-								if (msg.content[0].type !== 'function_request') {
-									const content = this.#prompt.contentToString(msg.content);
-									messages.push({ role: msg.role, content });
-								}
-							}
-						}
-					}
-					await this.#prompt.triggerRequest();
-					ws.sendToConnection(conn.id, JSON.stringify({
-						action: 'server_sessionloaded',
-						id,
-						content: messages
-					}));
-				}
-				if (msg.action === 'user_info') {
-					const id = msg.id;
-					const sessionInfo = this.#session.info();
-					const promptInfo = this.#prompt.info();
-					const info = `\nSESSION\n${sessionInfo}\nPROMPT\n${promptInfo}\nSERVER\nName: ${this.#name}\nDescription: ${this.#description}`;
-					ws.sendToConnection(conn.id, JSON.stringify({
-						action: 'server_info',
-						id,
-						content: info
-					}));
-				}
-			},
-			onConnection: async (conn) => {
-				return this.#auth(conn);
-			},
-			onClose: async (conn, reason) => {
-				deleteClient(this.#prompt.toolset, conn.id);
-			},
-			onError: async (conn, error) => {
-				deleteClient(this.#prompt.toolset, conn.id);
-				ws.closeConnection(conn.id);
-			}
-		});
-		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`);
-	}
-
-	/**
-	 * Broadcasts a reset message to all connected clients (starts new sessions).
-	 * @returns {void}
-	 * @fires reset - Via underlying prompt/clients.
-	 */
-	resetAll() {
-		ws.broadcast({ action: 'reset' });
-	}
-}
-
-export default AgentServer;