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

package/docs/jsdoc-best-practices.md

@@ -0,0 +1,278 @@
+# JSDoc Best Practices for JavaScript Modules
+
+## Introduction
+
+JSDoc is a markup language used to annotate JavaScript source code files. It allows developers to document their code in a structured way, generating documentation that is readable by humans and machines alike. This is particularly valuable for JavaScript modules, especially toolsets or utility libraries, where clear documentation helps users understand APIs, types, and usage.
+
+Best practices ensure documentation is consistent, comprehensive, and maintainable. Key benefits include:
+- Improved code readability and maintainability.
+- IDE support for autocompletion, type checking, and hover tooltips.
+- Generation of static HTML documentation sites.
+- Reusability across teams and projects.
+
+This guide focuses on documenting functions, classes, parameters, returns, and types, with examples tailored to utility libraries.
+
+## Documenting Modules
+
+Use the `@module` tag to mark a file as a module. All symbols in the file become module members. For utility libraries, document exports explicitly.
+
+### Example: Exporting Functions in a Utility Module
+```javascript
+/**
+ * @module utils/string
+ * String manipulation utilities.
+ */
+
+/**
+ * Formats a string by capitalizing the first letter.
+ * @param {string} str - The input string.
+ * @returns {string} The formatted string.
+ * @example
+ * capitalize("hello world"); // "Hello world"
+ */
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+module.exports = { capitalize };
+```
+
+This creates a documented module `module:utils/string` with exported member `module:utils/string.capitalize`.
+
+### Namespaces for Organization
+For larger libraries, use `@namespace` to group related utilities.
+```javascript
+/**
+ * @module math
+ * @namespace math.utils
+ */
+```
+
+## Documenting Functions
+
+Functions are the core of utility libraries. Use `@param` for parameters, `@returns` for return values, and include types and descriptions.
+
+### Basic Function Documentation
+```javascript
+/**
+ * Adds two numbers.
+ * @param {number} a - The first number.
+ * @param {number} b - The second number.
+ * @returns {number} The sum of a and b.
+ * @throws {Error} If inputs are not numbers.
+ * @example
+ * add(2, 3); // 5
+ */
+function add(a, b) {
+    if (typeof a !== "number" || typeof b !== "number") {
+        throw new Error("Inputs must be numbers");
+    }
+    return a + b;
+}
+```
+
+### Optional Parameters and Defaults
+```javascript
+/**
+ * Formats a number with thousand separators.
+ * @param {number} value - The number to format.
+ * @param {string} [separator=","] - The separator (default: comma).
+ * @returns {string} The formatted string.
+ * @example
+ * formatNumber(1000); // "1,000"
+ * formatNumber(1000, "."); // "1.000"
+ */
+function formatNumber(value, separator = ",") {
+    return value.toLocaleString("en-US", { separator });
+}
+```
+
+### Variadic (Rest) Parameters
+```javascript
+/**
+ * Sums multiple numbers.
+ * @param {...number} nums - Numbers to sum.
+ * @returns {number} The total sum.
+ * @example
+ * sum(1, 2, 3); // 6
+ */
+function sum(...nums) {
+    return nums.reduce((acc, n) => acc + n, 0);
+}
+```
+
+### Asynchronous Functions
+```javascript
+/**
+ * Fetches data asynchronously.
+ * @param {string} url - The URL to fetch.
+ * @returns {Promise<Object>} A promise resolving to the data.
+ */
+async function fetchData(url) {
+    const response = await fetch(url);
+    return response.json();
+}
+```
+
+## Documenting Classes
+
+For classes in utility libraries (e.g., a Validator class), document constructors, methods, and properties. JSDoc 3.4+ auto-detects ES6 classes.
+
+### Simple Class Example
+```javascript
+/**
+ * A utility class for validating inputs.
+ */
+class Validator {
+    /**
+     * Creates a new Validator instance.
+     * @param {Object} options - Configuration options.
+     * @param {boolean} [options.strict=false] - Strict mode.
+     */
+    constructor(options = {}) {
+        this.strict = options.strict || false;
+    }
+
+    /**
+     * Validates an email address.
+     * @param {string} email - The email to validate.
+     * @returns {boolean} True if valid.
+     * @memberof Validator
+     */
+    validateEmail(email) {
+        const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return regex.test(email);
+    }
+
+    /**
+     * Static method to validate without instance.
+     * @param {string} email - The email to validate.
+     * @returns {boolean} True if valid.
+     * @static
+     */
+    static isValidEmail(email) {
+        const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        return regex.test(email);
+    }
+}
+```
+
+### Extending Classes
+```javascript
+/**
+ * Advanced validator extending basic Validator.
+ * @extends Validator
+ */
+class AdvancedValidator extends Validator {
+    /**
+     * @param {Object} options - Options.
+     * @param {number} options.maxLength - Max length.
+     */
+    constructor(options) {
+        super(options);
+        this.maxLength = options.maxLength || 255;
+    }
+
+    /**
+     * Validates with length check.
+     * @param {string} str - The string.
+     * @returns {boolean} True if valid.
+     * @override
+     */
+    validateEmail(str) {
+        return super.validateEmail(str) && str.length <= this.maxLength;
+    }
+}
+```
+
+## Type Annotations
+
+Use types in curly braces `{}` for precision. Define complex types with `@typedef` for reuse.
+
+### Basic Types
+- Primitives: `{string}`, `{number}`, `{boolean}`
+- Arrays: `{string[]}` or `{Array.<string>}`
+- Objects: `{Object}`
+- Unions: `{string|number}`
+- Nullable: `{string?}`
+- Any: `{*}`
+- Promises: `{Promise<string>}`
+
+### Variables and Properties
+```javascript
+/** @type {string} */
+let message = "Hello";
+
+/**
+ * User object type.
+ * @typedef {Object} User
+ * @property {string} name - User name.
+ * @property {number} age - User age.
+ * @property {string[]} hobbies - User hobbies.
+ */
+
+/** @type {User} */
+const user = { name: "Alice", age: 30, hobbies: ["reading"] };
+```
+
+### In Parameters and Returns
+Types are integrated into `@param` and `@returns`:
+```javascript
+/**
+ * Processes a user.
+ * @param {User} user - The user object.
+ * @returns {User} Processed user.
+ */
+function processUser(user) {
+    return { ...user, processed: true };
+}
+```
+
+## Advanced: Typedefs for Complex Types
+For utility libraries, define reusable types:
+```javascript
+/**
+ * Response from API.
+ * @typedef {Object} ApiResponse
+ * @property {boolean} success - Success flag.
+ * @property {any} data - Response data.
+ * @property {string} [error] - Error message if failed.
+ */
+
+/**
+ * Fetches API data.
+ * @param {string} endpoint - API endpoint.
+ * @returns {Promise<ApiResponse>} The API response.
+ */
+async function apiFetch(endpoint) {
+    // Implementation
+}
+```
+
+## Best Practices
+
+1. **Consistency**: Use the same style for all docs (e.g., always include types, descriptions).
+2. **Readability**: 
+   - Start descriptions with a capital letter and end with a period.
+   - Use hyphens for parameter descriptions: `@param {type} name - Description.`
+   - Keep comments concise but informative.
+3. **Completeness**: Document all public APIs; use `@private` or `@internal` for internals.
+4. **Examples**: Include `@example` blocks for complex usage.
+5. **Namespaces**: Group related items with `@namespace` and `@memberOf` for large libraries.
+   ```javascript
+   /**
+    * @namespace utils.array
+    * Array utility functions.
+    */
+   ```
+6. **Error Handling**: Use `@throws` for possible exceptions.
+7. **Links**: Use `@see` for related items, `@link` for external.
+8. **IDE Integration**: Test in VS Code or WebStorm for type hints.
+9. **Generation**: Use JSDoc CLI (`jsdoc yourfile.js`) to generate HTML docs. Configure with `jsdoc.json` for templates like docdash.
+10. **Maintenance**: Update docs alongside code changes; treat as code.
+
+For toolsets/utility libraries, prioritize documenting exports and focus on user-facing APIs to make integration easy.
+
+## References
+- [Official JSDoc Documentation](https://jsdoc.app/)
+- [JSDoc Tags](https://jsdoc.app/tags-*)

package/docs/multi-agent-clusters.md

@@ -0,0 +1,265 @@
+# Multi-Agent Clusters in Dave: v0.0.9
+
+Welcome to the exciting world of **Multi-Agent Clusters** in the Dave framework! 🚀 If you're ready to scale your AI agents into powerful, collaborative clusters, you've come to the right place. This guide walks you through setting up CodeServer with PM2, spawning agents, launching in server mode, connecting clients, querying sessions, managing with PM2, testing, and more. By the end, you'll have a robust cluster humming along, enabling self-aware, interconnected agents. Let's dive in step-by-step!
+
+Note: Dave v0.0.9 is fully ESM (ECMAScript Modules) consistent. All JavaScript examples use `import`/`export` syntax—no CommonJS `require`/`module.exports`.
+
+## CodeServer PM2 Setup
+
+CodeServer is the backbone of your multi-agent cluster, providing a WebSocket-based server for agent communication. It integrates seamlessly with PM2 for process management, ensuring high availability and easy scaling.
+
+### Prerequisites
+- Node.js (v18+ recommended)
+- PM2 installed globally: `npm install -g pm2`
+- Dave project cloned and dependencies installed: `npm install`
+
+### Step-by-Step Setup
+1. **Choose Your Launch Method**:
+   - Use the binary script: `./bin/codeDave` (convenient for quick starts).
+   - Or the shell script: `./agents/codeserver.sh` (for more customization).
+
+2. **Default Configuration**:
+   - **Port**: 9000 (change with `--port 8080` if needed).
+   - **Secret**: "123" (for secure WebSocket connections; override with `--secret your_secret`).
+
+3. **Launch CodeServer with PM2**:
+   Run the following to start CodeServer as a PM2-managed process:
+   ```
+   pm2 start ./bin/codeDave --name "hello-dave_code_9000" -- --serve --port 9000 --secret 123
+   ```
+   - `--serve`: Enables server mode (detailed below).
+   - This creates a process named `hello-dave_code_9000` for easy identification.
+
+4. **Verify Setup**:
+   - Check PM2 status: `pm2 list` (look for `hello-dave_code_9000` in "online" status).
+   - Test connection: Use a WebSocket client to connect to `ws://127.0.0.1:9000/ws` with secret "123".
+
+## Creating Agents via spawn_agent
+
+Spawning agents is where the magic happens! Use the `spawn_agent` function to dynamically create and integrate new agents into your cluster. In v0.0.9, spawning is primarily via CLI for seamless integration with the ESM project structure.
+
+### Reference to spawn_agent Blueprint
+For a deep dive into `spawn_agent`, check the [spawn_agent blueprint](../blueprints/spawn-agent.md) (or implement based on the core Dave agent manager patterns in [agent-manager.md](./agent-manager.md)).
+
+### Step-by-Step Agent Creation
+1. **CLI Spawning (Recommended)**:
+   Use the `./agents/spawn_agent.js` script to spawn agents directly from the command line, attaching them to the cluster:
+   ```
+   ./agents/spawn_agent.js "Create weather predictor agent with prompt: You are a weather prediction agent. Use tools to fetch data." --connect ws://127.0.0.1:9000/ws --secret 123 --tools web_search,weather_api
+   ```
+   - This spawns the agent (e.g., named "weatherPredictor" based on description), registers it with CodeServer, and enables collaborative querying.
+   - Flags: `--connect` for cluster attachment, `--secret` for authentication, `--tools` for tool assignment.
+
+2. **Integration with Cluster**:
+   - Agents auto-register with CodeServer upon spawn via the CLI.
+   - For programmatic control in ESM scripts, import and use as shown in examples below.
+
+## Launching Server Mode (--serve)
+
+Server mode turns CodeServer into a persistent hub for multi-agent interactions.
+
+1. **Command**:
+   ```
+   ./bin/codeDave --serve --port 9000 --secret 123
+   ```
+
+2. **What Happens**:
+   - Listens on WebSocket endpoint `/ws`.
+   - Handles agent registrations and session management.
+   - Supports multiple concurrent clients.
+
+3. **PM2 Integration**:
+   As shown in setup, wrap it in PM2 for daemonization and auto-restart.
+
+## Attaching Clients (--connect)
+
+Clients (like other Dave instances or tools) connect to the cluster for tool calls and session sharing.
+
+1. **Basic Connection**:
+   ```
+   ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123
+   ```
+   - This attaches the client as a tool-calling endpoint.
+   - Use in scripts for agent-to-agent communication.
+
+2. **Advanced Usage**:
+   - Pipe inputs: `echo "query" | ./bin/dave.js --connect ...`
+   - Handle toolcalls: Clients receive and execute tools on behalf of the cluster.
+
+## Querying via bin/dave.js --connect
+
+For one-shot queries or building sessions, use `bin/dave.js` with connection flags.
+
+### One-Shot Example
+Predict weather with a quick query:
+```
+echo "predict weather in NYC" | ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123
+```
+- Builds a temporary session, routes to relevant agents (e.g., weatherPredictor), and returns results.
+
+### Session Building
+For persistent sessions:
+```
+./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123 --session my_weather_session
+```
+- Follow with queries to maintain state across interactions.
+
+## PM2 Start/Stop/Reload
+
+PM2 makes cluster management a breeze!
+
+1. **List Processes**:
+   ```
+   pm2 list
+   ```
+   - Shows status of `hello-dave_code_9000` and other agents.
+
+2. **Start/Stop**:
+   ```
+   pm2 start hello-dave_code_9000  # Start
+   pm2 stop hello-dave_code_9000   # Stop
+   pm2 restart hello-dave_code_9000 # Restart
+   ```
+
+3. **Reload (Zero-Downtime)**:
+   ```
+   pm2 reload hello-dave_code_9000
+   ```
+   - Ideal for updates without interrupting sessions.
+
+4. **Logs and Monitoring**:
+   ```
+   pm2 logs hello-dave_code_9000
+   pm2 monit
+   ```
+
+## Testing One-Shots and Sessions
+
+Ensure your cluster is rock-solid with these tests.
+
+### One-Shot Testing
+1. Spawn a test agent.
+2. Run: `echo "test query" | ./bin/dave.js --connect ...`
+3. Verify output matches expected (e.g., no errors, relevant response).
+
+### Session Testing
+1. Start a session: `./bin/dave.js --connect ... --session test`
+2. Send multiple queries: `echo "first" | ...` then `echo "follow-up" | ...`
+3. Check session persistence (e.g., context retained).
+
+### End-to-End Test Script
+```bash
+#!/bin/bash
+# test_cluster.sh
+pm2 start ./bin/codeDave --name "test_code" -- --serve --port 9000 --secret 123
+sleep 2
+echo "Hello cluster!" | ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123
+pm2 stop test_code
+```
+
+## Self-Awareness: Detecting PM2/CodeServer in Prompts
+
+Make your agents smarter by embedding cluster awareness! In v0.0.9, self-awareness leverages argument detection and initial PM2 inspection for accurate blueprint compliance.
+
+- **In Agent Prompts**:
+  Include detection logic: "If running under PM2/CodeServer (detect via args like --serve/--connect or initial `pm2 list` inspect), coordinate with cluster agents."
+
+- **Implementation** (ESM Syntax):
+  Agents auto-detect via argument parsing and PM2 inspection:
+  ```javascript
+  import { execSync } from 'child_process';
+  import { process } from 'process'; // Built-in
+
+  const args = process.argv.slice(2);
+  const isServeMode = args.includes('--serve');
+  const isConnectMode = args.includes('--connect');
+  const pm2Status = execSync('pm2 list', { encoding: 'utf8' }).includes('hello-dave_code_9000');
+
+  if (isServeMode || isConnectMode || pm2Status) {
+    // Cluster mode: Share context, route to other agents
+    console.log('Detected cluster environment');
+  }
+  ```
+  This enables self-aware routing, e.g., "Delegate weather query to weatherPredictor in cluster." Aligns with blueprint by inspecting PM2 initially for process awareness.
+
+## Mermaid Diagram: Cluster Architecture
+
+Visualize your setup!
+
+```mermaid
+graph TD
+    A[PM2 Manager] --> B[CodeServer<br/>Port 9000 /ws]
+    B --> C[Agent 1<br/>spawn_agent()]
+    B --> D[Agent 2<br/>e.g., WeatherPredictor]
+    E[Client / bin/dave.js] -->|connect| B
+    E -->|one-shot| F[Session Builder]
+    G[Tools: web_search, etc.] <-->|toolcalls| C
+    G <-->|toolcalls| D
+    style B fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+- **Nodes**: PM2 oversees CodeServer, which hubs agents and clients.
+- **Flows**: Connections for spawning, querying, and tool execution.
+
+## Examples
+
+### Full ESM Node Script for Custom Agent Launch (--serve)
+Here&apos;s a complete ESM script (`custom-agent-launch.mjs`) to spawn and launch a custom agent in server mode:
+
+```javascript
+#!/usr/bin/env node
+// custom-agent-launch.mjs - ESM for v0.0.9
+
+import { spawn_agent } from &apos;./agents/spawn.js&apos;; // ESM import
+import { connectToCluster } from &apos;./utils/cluster.js&apos;; // Hypothetical utility
+
+async function main() {
+  const agentConfig = {
+    name: &quot;queryMaster&quot;,
+    prompt: &quot;You are a master query router in the cluster.&quot;,
+    tools: [&apos;web_search&apos;],
+    cluster: &quot;ws://127.0.0.1:9000/ws&quot;
+  };
+
+  // Spawn the agent
+  const agent = await spawn_agent(agentConfig);
+  
+  // Connect to cluster if in server mode
+  if (process.argv.includes(&apos;--serve&apos;)) {
+    await connectToCluster(agent, { secret: &quot;123&quot; });
+    console.log(&apos;Agent launched in server mode!&quot;);
+  }
+}
+
+main().catch(console.error);
+```
+
+Run it: `node custom-agent-launch.mjs --serve`
+
+### Full Cluster Spawn and Query (CLI + ESM)
+1. Start CodeServer: `pm2 start ./bin/codeDave --name code_9000 -- --serve --port 9000 --secret 123`
+2. Spawn Agent (CLI):
+   ```
+   ./agents/spawn_agent.js &quot;Create queryMaster: You are a master query router.&quot; --connect ws://127.0.0.1:9000/ws --secret 123
+   ```
+3. Query: `echo &quot;What&apos;s the plan?&quot; | ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123`
+
+### Multi-Agent Collaboration
+- Spawn multiple: weather, news, summary agents.
+- Query: &quot;Summarize today&apos;s news and weather&quot; → Routes to respective agents via cluster.
+
+## Troubleshooting
+
+- **Connection Refused**: Ensure CodeServer is running (`pm2 list`) and port 9000 is free (`lsof -i :9000`).
+- **Secret Mismatch**: Double-check `--secret` flags match.
+- **PM2 Crashes**: View logs (`pm2 logs`)—common issues: missing deps or port conflicts. Restart: `pm2 restart all`.
+- **Agent Not Attaching**: Verify `spawn_agent` cluster URL and secret. Test WebSocket manually.
+- **Session Loss**: Check PM2 memory limits (`pm2 desc code_9000`); increase if needed.
+- **One-Shot Fails**: Ensure input is piped correctly; debug with `--verbose`.
+- **ESM Import Errors**: Ensure `package.json` has &quot;type&quot;: &quot;module&quot; and files use `.mjs` or `.js` with ESM syntax.
+
+If issues persist, reference [project-overview.md](./project-overview.md) or spawn a debug agent!
+
+---
+
+*Ready for v0.0.9 deployment! Cluster up and conquer those multi-agent challenges. 🎉 Questions? Ping the Dave community.*