@j-o-r/hello-dave 0.0.6 → 0.0.8

package/lib/AgentManager.js

@@ -1,56 +1,83 @@
 import { Prompt, Cli, AgentClient, AgentServer, API, ToolSet, Session, env } from './index.js';
 import toolsPool from './genericToolset.js'
 /**
-* @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
-*/
+ * @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 - Model options
-* @property {'gpt'|'xai'|'claude'} api - AI endpoint to use
-* @property {number} [contextWindow] - The size in tokens for the context/session
-* @property {'auto'|'required'|void} [toolsetMode] - 
-* @property {boolean} [debug] - verbose output
-*/
+ * @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
-* @property {string} secret - Secret string for WS access authorisation (server and client secrets should match)
-* @property {string} [cachePath] - path to session/record storage 
-*/
+ * @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 {
-	/** @type {Prompt} */
+	/** @private @type {Prompt} */
   #prompt;
-  /** @type {Session} */
+  /** @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 = '';
+
   /**
-  * @param {Options} options
-  */
+   * 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');
     } 
-    const validNameRegex = /^[a-z_0-9]{2,}$/;
     if (!validNameRegex.test(this.#name)) {
-      throw new Error(`Invalid agent 'name' in options: '${this.#name}'. Must match /^[a-z_0-9]{2,}$/ (lowercase a-z, digits, underscores; min 2 chars).`);
+      throw new Error(`Invalid agent 'name': '${this.#name}'. Must match /^[a-z_0-9]{2,}$/`);
     }
     this.#cachePath = options.cachePath || this.#cachePath;
   }
 
   /**
-  * @param {Setup} setup
-  */
+   * 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,
@@ -63,9 +90,6 @@ class AgentManager {
     this.#sysPrompt = prompt;
     this.#contextWindow = contextWindow;
     if (options?.model) this.#model = options.model;
-    this.#sysPrompt = prompt;
-    this.#contextWindow = contextWindow;
-    if (options?.model) this.#model = options.model;
     let toolset;
     if (toolsetMode) {
     	toolset = new ToolSet(toolsetMode);
@@ -77,43 +101,48 @@ class AgentManager {
     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; // For chaining
+    return this;
   }
 
   /**
-  * Start a CLI for local usage
-  * @param {string} description - introduction message for the CLI user
-  */
+   * @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(() => {
-      // This resolves issues with log output after the console has been started
       cli.start();
     }, 1000);
   }
 
   /**
-  * Attach a session to an AgentServer
-  * DO NOT ATTACH TO SELF, however, when in server mode
-  * An AgentServer can attach as client to another server
-  * @param {string} name - function_call name
-  * @param {string} description - function_call description
-  * @param {string} [url='ws://127.0.0.1:8000/ws'] - ws URL
-  */
+   * @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 });
   }
 
   /**
-  * Start the Agent in server mode.
-  * A server is always started on localhost
-  * Clients can attach now and are accesible as via function_calls (toolset)  
-  * @param {string} name - function_call name
-  * @param {string} description - function_call description
-  * @param {number} [port=8000] - Start the dynamic toolset server on this port
-  */
+   * @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');
@@ -125,64 +154,68 @@ class AgentManager {
     	prompt: this.#prompt,
     	session: this.#sessionStorage,
     	debug: this.#debug
-    	
     });
-    // trigger reset on all Agents
     this.#prompt.on('reset', () => {
-    	// Generate new context for all Agents
     	server.resetAll();
-    })
+    });
   }
+
   /**
-  * Direct call to the prompt
-  * @param {string} input
-  * @returns {Promise<string>}
-  */
+   * Direct synchronous call to the underlying Prompt.
+   * @param {string} input - User input.
+   * @returns {Promise&lt;string&gt;} Response.
+   * @throws {Error} No setup.
+   */
   async directCall(input) {
 		const res = await this.#prompt.call(input);
   	return res;
   }
-  /** @returns {Prompt} */
+
+  /** @returns {Prompt} Underlying Prompt instance. */
   getPrompt() { return this.#prompt; }
-  /** @returns {ToolSet|void} */
+
+  /** @returns {ToolSet|null} Toolset if configured. */
   getToolset() { return this.#prompt.toolset; }
-  /** @returns {Promise<import('./fafs.js').EnvironmentInfo>} */
+
+  /** @returns {Promise&lt;import('./fafs.js').EnvironmentInfo&gt;} System env info. */
   async environment() {
   	return env();
   }
+
   /**
-   * Adds a pre-defined generic tool from lib/genericToolset.js 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 - Valid generic tool name (validated /^[a-z_0-9]{2,}$/).
-   * @throws {Error} If toolset not initialized or tool not found in pool.
+   * Adds a pre-defined generic tool from toolsPool 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) {
-    const validNameRegex = /^[a-z_0-9]{2,}$/;
     if (!validNameRegex.test(name)) {
-      throw new Error(`Invalid 'name': '${name}'. Must match /^[a-z_0-9]{2,}$/ (lowercase a-z, digits, underscores; min 2 chars).`);
+      throw new Error(`Invalid 'name': '${name}'. Must match /^[a-z_0-9]{2,}$/`);
     }
-    if (!this.#prompt.toolset) throw new Error('No ToolSet defined')
+    if (!this.#prompt.toolset) throw new Error('No ToolSet defined');
     let tool = toolsPool.get(name);
-    if (!tool) throw new Error('Tool not defined')
+    if (!tool) throw new Error(`Tool '${name}' not found in pool`);
     this.#prompt.toolset.add(name, tool.description, tool.parameters, tool.method);
   }
   
   /**
-   * Smart launcher: Dispatches to CLI/server/attach/direct. Auto-gens cliIntro/desc if empty.
-   * @param {number} [servePort] - Server port (if no input).
-   * @param {string} [connectUrl] - WS to attach. e.g. ws://127.0.0.1:8091/ws
-   * @param {string} [cliIntro=""] - CLI intro (auto-gen if falsy).
-   * @param {string} [toolName=""] - name /^[a-z_0-9]{2,}$/ Tool name for server/attach (defaults to agent.name).
-   * @param {string} [toolDescription=""] - Tool desc (auto-gen if falsy).
+   * 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&lt;void&gt;}
+   * @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");
 
-    const validNameRegex = /^[a-z_0-9]{2,}$/;
-
     toolName = toolName || this.#name;
-    // Validate 'toolName' (or fallback agent name)
     if (!validNameRegex.test(toolName)) {
-      throw new Error(`Invalid 'toolName' (or agent #name): '${toolName}'. Must match /^[a-z_0-9]{2,}$/ (lowercase a-z, digits, underscores; min 2 chars).`);
+      throw new Error(`Invalid 'toolName': '${toolName}'. Must match /^[a-z_0-9]{2,}$/`);
     }
 
     if (!toolDescription && this.#sysPrompt) {
@@ -190,22 +223,20 @@ class AgentManager {
     }
 
     if (!cliIntro) {
-      const introStr = this.#name + " " + (this.#model || "unknown-model") + " - context: " + this.#contextWindow;
+      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);
-      // A server can also be a client
       if (connectUrl) {
         this.#attach(toolName, toolDescription, connectUrl);
       }
     } else if (connectUrl) {
-      // Connect to a agent 'server' and enable via websocket / toolcalls
       this.#attach(toolName, toolDescription, connectUrl);
     } else {
-      // Terminal user CLI
       this.#startCli(cliIntro);
     }
   }