@j-o-r/hello-dave 0.1.1 → 0.1.5

package/docs/howtos/spawn-agents.md.bak

@@ -1,200 +0,0 @@
-# Spawning and Managing Agents
-
-This guide covers how to directly call agents, use the Spawn Dave workflow, and utilize Spawn Agent for creating, testing, and improving agents. It includes practical examples in Bash and JavaScript, as well as concepts for self-improvement loops. For foundational concepts on agent interactions, refer to [agent-networking.md](./agent-networking.md).
-
-## 1. Direct Agent Calls
-
-Direct agent calls allow you to invoke specific agents from the command line or scripts without spawning a full workflow. This is useful for quick queries or testing individual agent behaviors.
-
-### Real Project Example: Calling GPT Agent
-
-In the project, you can directly invoke the GPT agent using the provided script.
-
-**JavaScript Snippet (examples/gpt_agent.js):**
-```javascript
-// examples/gpt_agent.js
-const { createAgent } = require('../lib/agent-factory'); // Assuming agent factory module
-
-async function runAgent(query) {
-  const agent = createAgent('gpt'); // Initialize GPT agent
-  const response = await agent.process(query);
-  console.log(response);
-}
-
-if (require.main === module) {
-  const query = process.argv[2];
-  if (!query) {
-    console.error('Usage: node examples/gpt_agent.js "your query"');
-    process.exit(1);
-  }
-  runAgent(query).catch(console.error);
-}
-```
-
-**Bash Command to Run:**
-```bash
-node examples/gpt_agent.js "What is the capital of France?"
-# Output: Paris (or similar GPT response)
-```
-
-This is a real example from the project, enabling straightforward execution. Extend it by passing additional flags for configuration, e.g., `--model gpt-4`.
-
-## 2. Spawn Dave Workflow
-
-The Spawn Dave workflow (examples/spawn_dave.js) is a predefined sequence for initializing a "Dave" agent instance, which handles complex tasks like multi-step reasoning or integration with external tools.
-
-### Overview
-- **Purpose:** Spawn a Dave agent that can orchestrate sub-agents or workflows.
-- **Key Features:** Tool integration, state management, and logging.
-
-### Example: Running Spawn Dave
-
-**JavaScript Snippet (examples/spawn_dave.js):**
-```javascript
-// examples/spawn_dave.js
-const { spawnDave } = require('../workflows/spawn-dave'); // Import workflow
-
-async function main(task) {
-  const dave = await spawnDave({ 
-    tools: ['web_search', 'code_executor'], 
-    model: 'gpt-4' 
-  });
-  const outcome = await dave.execute(task);
-  console.log('Dave's response:', outcome);
-}
-
-if (require.main === module) {
-  const task = process.argv[2] || 'Default task: Analyze market trends.';
-  main(task).catch(console.error);
-}
-```
-
-**Bash Command:**
-```bash
-node examples/spawn_dave.js "Summarize recent AI advancements."
-```
-
-This workflow automatically handles agent lifecycle: spawn, execute, and cleanup. For networking multiple Daves, see [agent-networking.md](./agent-networking.md).
-
-## 3. Spawn Agent (examples/spawn_agent.js or agentDave)
-
-Spawn Agent is a utility for dynamically creating, testing, and improving agents based on outcomes. It's ideal for iterative development, where agents self-improve through workflows and tests. The entry point is `examples/spawn_agent.js`, which can be aliased as `agentDave` via the `package.json` scripts (e.g., `npm run agentDave -- create ...`).
-
-### Core Functionality
-- **Creating Agents:** Define agent specs (prompts, tools, models) and spawn instances.
-- **Testing:** Run predefined tests to evaluate performance.
-- **Improving:** Use feedback loops to refine prompts or configurations based on outcomes.
-- **Self-Improvement Loops:** Agents can analyze their own outputs and suggest updates.
-
-### Example: Basic Spawn and Test
-
-**Bash Usage (via examples/spawn_agent.js or npm run agentDave):**
-```bash
-# Spawn a new agent for math tasks
-node examples/spawn_agent.js create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
-
-# Or using alias
-npm run agentDave -- create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
-
-# Test the agent
-node examples/spawn_agent.js test --name math-solver --input "2+2*3" --expected 8
-
-# Improve based on outcomes
-node examples/spawn_agent.js improve --name math-solver --feedback "Failed on algebra; add quadratic formula."
-```
-
-**JavaScript Integration (Custom Script):**
-```javascript
-// test-spawn.js
-const { spawnAgent, testAgent, improveAgent } = require('../examples/spawn_agent');
-
-async function workflow() {
-  // Create
-  const agent = await spawnAgent({
-    name: 'researcher',
-    tools: ['web_search', 'browse_page'],
-    prompt: 'Conduct thorough research on topics.'
-  });
-
-  // Test
-  const testResult = await testAgent(agent, { query: 'Latest on quantum computing', expected: /qubits/ });
-  console.log('Test passed:', testResult.passed);
-
-  // Self-Improvement Loop
-  if (!testResult.passed) {
-    const improvements = await improveAgent(agent, testResult.feedback);
-    console.log('Suggested improvements:', improvements);
-    // Re-spawn with updates
-    const updatedAgent = await spawnAgent({ ...agent.config, prompt: improvements.newPrompt });
-  }
-}
-
-workflow().catch(console.error);
-```
-
-**Running the Script:**
-```bash
-node test-spawn.js
-```
-
-### Self-Improvement Loops
-Implement loops where agents evaluate their performance using tools like `test_agent.js` for testing and `memory_agent` for storing past evaluations and improvements.
-
-1. **Execute Task:** Run agent on input.
-2. **Evaluate Outcome:** Use `test_agent.js` to compare against benchmarks.
-3. **Store and Generate Improvements:** Leverage `memory_agent` to recall past failures and suggest refinements.
-4. **Update and Iterate:** Apply changes and re-test.
-
-**Example Loop in JS (using test_agent.js and memory_agent):**
-```javascript
-// self-improve-loop.js
-const { spawnAgent } = require('../examples/spawn_agent');
-const { testAgent } = require('../examples/test_agent');
-const { memoryAgent } = require('../lib/memory_agent'); // Assuming memory agent for evaluation storage
-
-async function selfImproveLoop(initialConfig, task, maxIterations = 5) {
-  let agent = await spawnAgent(initialConfig);
-  const memory = memoryAgent(); // For storing evaluations
-
-  for (let i = 0; i < maxIterations; i++) {
-    const result = await agent.execute(task);
-    const testResult = await testAgent(agent, { input: task, output: result, expected: /desired pattern/ });
-    
-    // Store in memory
-    await memory.store({ iteration: i, test: testResult });
-    
-    if (testResult.passed) {
-      console.log('Improvement loop converged.');
-      break;
-    }
-    
-    // Retrieve past suggestions from memory
-    const pastFeedback = await memory.retrieve('improvements');
-    const improvements = await agent.suggestImprovements(testResult.feedback, pastFeedback);
-    agent.updateConfig(improvements);
-    
-    console.log(`Iteration ${i + 1}: Updated agent config.`);
-  }
-  
-  return agent;
-}
-
-// Usage
-selfImproveLoop(
-  { name: 'improving-agent', prompt: 'Initial prompt.' },
-  'Complex query here.'
-).catch(console.error);
-```
-
-For scaling to networks of agents, integrate with concepts from [agent-networking.md](./agent-networking.md), such as peer-to-peer spawning.
-
-## Best Practices
-- Always backup agent configs before improvements.
-- Use version control for agent definitions (e.g., JSON specs in `./agents/`).
-- Monitor resource usage in loops to avoid infinite iterations.
-- Test in isolated environments.
-
-## Upcoming Features (v0.0.7)
-For planned enhancements related to agent spawning, testing, and self-improvement, refer to the tasks outlined in [TODO.md](../TODO.md). This includes improvements to loop efficiency, better memory integration, and expanded tool support.
-
-For more on agent workflows, explore related docs like [agent-networking.md](./agent-networking.md).

package/docs/howtos/spawn-agents.md.bak_new

@@ -1,200 +0,0 @@
-# Spawning and Managing Agents
-
-This guide covers how to directly call agents, use the Spawn Dave workflow, and utilize Spawn Agent for creating, testing, and improving agents. It includes practical examples in Bash and JavaScript, as well as concepts for self-improvement loops. For foundational concepts on agent interactions, refer to [agent-networking.md](./agent-networking.md).
-
-## 1. Direct Agent Calls
-
-Direct agent calls allow you to invoke specific agents from the command line or scripts without spawning a full workflow. This is useful for quick queries or testing individual agent behaviors.
-
-### Real Project Example: Calling GPT Agent
-
-In the project, you can directly invoke the GPT agent using the provided script.
-
-**JavaScript Snippet (examples/gpt_agent.js):**
-```javascript
-// examples/gpt_agent.js
-const { createAgent } = require('../lib/agent-factory'); // Assuming agent factory module
-
-async function runAgent(query) {
-  const agent = createAgent('gpt'); // Initialize GPT agent
-  const response = await agent.process(query);
-  console.log(response);
-}
-
-if (require.main === module) {
-  const query = process.argv[2];
-  if (!query) {
-    console.error('Usage: node examples/gpt_agent.js "your query"');
-    process.exit(1);
-  }
-  runAgent(query).catch(console.error);
-}
-```
-
-**Bash Command to Run:**
-```bash
-node examples/gpt_agent.js "What is the capital of France?"
-# Output: Paris (or similar GPT response)
-```
-
-This is a real example from the project, enabling straightforward execution. Extend it by passing additional flags for configuration, e.g., `--model gpt-4`.
-
-## 2. Spawn Dave Workflow
-
-The Spawn Dave workflow (examples/spawn_dave.js) is a predefined sequence for initializing a "Dave" agent instance, which handles complex tasks like multi-step reasoning or integration with external tools.
-
-### Overview
-- **Purpose:** Spawn a Dave agent that can orchestrate sub-agents or workflows.
-- **Key Features:** Tool integration, state management, and logging.
-
-### Example: Running Spawn Dave
-
-**JavaScript Snippet (examples/spawn_dave.js):**
-```javascript
-// examples/spawn_dave.js
-const { spawnDave } = require('../workflows/spawn-dave'); // Import workflow
-
-async function main(task) {
-  const dave = await spawnDave({ 
-    tools: ['web_search', 'code_executor'], 
-    model: 'gpt-4' 
-  });
-  const outcome = await dave.execute(task);
-  console.log('Dave's response:', outcome);
-}
-
-if (require.main === module) {
-  const task = process.argv[2] || 'Default task: Analyze market trends.';
-  main(task).catch(console.error);
-}
-```
-
-**Bash Command:**
-```bash
-node examples/spawn_dave.js "Summarize recent AI advancements."
-```
-
-This workflow automatically handles agent lifecycle: spawn, execute, and cleanup. For networking multiple Daves, see [agent-networking.md](./agent-networking.md).
-
-## 3. Spawn Agent (examples/spawn_agent.js or agentDave)
-
-Spawn Agent is a utility for dynamically creating, testing, and improving agents based on outcomes. It's ideal for iterative development, where agents self-improve through workflows and tests. The entry point is `examples/spawn_agent.js`, which can be aliased as `agentDave` via the `package.json` scripts (e.g., `npm run agentDave -- create ...`).
-
-### Core Functionality
-- **Creating Agents:** Define agent specs (prompts, tools, models) and spawn instances.
-- **Testing:** Run predefined tests to evaluate performance.
-- **Improving:** Use feedback loops to refine prompts or configurations based on outcomes.
-- **Self-Improvement Loops:** Agents can analyze their own outputs and suggest updates.
-
-### Example: Basic Spawn and Test
-
-**Bash Usage (via examples/spawn_agent.js or npm run agentDave):**
-```bash
-# Spawn a new agent for math tasks
-node examples/spawn_agent.js create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
-
-# Or using alias
-npm run agentDave -- create --name math-solver --tools calculator --prompt "Solve math problems step-by-step."
-
-# Test the agent
-node examples/spawn_agent.js test --name math-solver --input "2+2*3" --expected 8
-
-# Improve based on outcomes
-node examples/spawn_agent.js improve --name math-solver --feedback "Failed on algebra; add quadratic formula."
-```
-
-**JavaScript Integration (Custom Script):**
-```javascript
-// test-spawn.js
-const { spawnAgent, testAgent, improveAgent } = require('../examples/spawn_agent');
-
-async function workflow() {
-  // Create
-  const agent = await spawnAgent({
-    name: 'researcher',
-    tools: ['web_search', 'browse_page'],
-    prompt: 'Conduct thorough research on topics.'
-  });
-
-  // Test
-  const testResult = await testAgent(agent, { query: 'Latest on quantum computing', expected: /qubits/ });
-  console.log('Test passed:', testResult.passed);
-
-  // Self-Improvement Loop
-  if (!testResult.passed) {
-    const improvements = await improveAgent(agent, testResult.feedback);
-    console.log('Suggested improvements:', improvements);
-    // Re-spawn with updates
-    const updatedAgent = await spawnAgent({ ...agent.config, prompt: improvements.newPrompt });
-  }
-}
-
-workflow().catch(console.error);
-```
-
-**Running the Script:**
-```bash
-node test-spawn.js
-```
-
-### Self-Improvement Loops
-Implement loops where agents evaluate their performance using tools like `test_agent.js` for testing and `memory_agent` for storing past evaluations and improvements.
-
-1. **Execute Task:** Run agent on input.
-2. **Evaluate Outcome:** Use `test_agent.js` to compare against benchmarks.
-3. **Store and Generate Improvements:** Leverage `memory_agent` to recall past failures and suggest refinements.
-4. **Update and Iterate:** Apply changes and re-test.
-
-**Example Loop in JS (using test_agent.js and memory_agent):**
-```javascript
-// self-improve-loop.js
-const { spawnAgent } = require('../examples/spawn_agent');
-const { testAgent } = require('../examples/test_agent');
-const { memoryAgent } = require('../lib/memory_agent'); // Assuming memory agent for evaluation storage
-
-async function selfImproveLoop(initialConfig, task, maxIterations = 5) {
-  let agent = await spawnAgent(initialConfig);
-  const memory = memoryAgent(); // For storing evaluations
-
-  for (let i = 0; i < maxIterations; i++) {
-    const result = await agent.execute(task);
-    const testResult = await testAgent(agent, { input: task, output: result, expected: /desired pattern/ });
-    
-    // Store in memory
-    await memory.store({ iteration: i, test: testResult });
-    
-    if (testResult.passed) {
-      console.log('Improvement loop converged.');
-      break;
-    }
-    
-    // Retrieve past suggestions from memory
-    const pastFeedback = await memory.retrieve('improvements');
-    const improvements = await agent.suggestImprovements(testResult.feedback, pastFeedback);
-    agent.updateConfig(improvements);
-    
-    console.log(`Iteration ${i + 1}: Updated agent config.`);
-  }
-  
-  return agent;
-}
-
-// Usage
-selfImproveLoop(
-  { name: 'improving-agent', prompt: 'Initial prompt.' },
-  'Complex query here.'
-).catch(console.error);
-```
-
-For scaling to networks of agents, integrate with concepts from [agent-networking.md](./agent-networking.md), such as peer-to-peer spawning.
-
-## Best Practices
-- Always backup agent configs before improvements.
-- Use version control for agent definitions (e.g., JSON specs in `./agents/`).
-- Monitor resource usage in loops to avoid infinite iterations.
-- Test in isolated environments.
-
-## Upcoming Features (v0.0.7)
-For planned enhancements related to agent spawning, testing, and self-improvement, refer to the tasks outlined in [TODO.md](../TODO.md). This includes improvements to loop efficiency, better memory integration, and expanded tool support.
-
-For more on agent workflows, explore related docs like [agent-networking.md](./agent-networking.md).

package/docs/multi-agent-clusters.md

@@ -1,265 +0,0 @@
-# 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.*