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

package/docs/howtos/agent-networking.md

@@ -0,0 +1,253 @@
+# Agent Networking How-Tos
+
+## Table of Contents
+- [Introduction](#introduction)
+- [Current Howtos Files](#current-howtos-files)
+- [Overview of Agent Networking](#overview-of-agent-networking)
+- [Setup Steps](#setup-steps)
+- [Using --serve Flag](#using--serve-flag)
+- [Using --connect Flag](#using--connect-flag)
+- [Multi-Agent Chains via CodeServer](#multi-agent-chains-via-codeserver)
+- [Examples](#examples)
+- [Bash Examples from codeserver.sh](#bash-examples-from-codeserver-sh)
+- [JavaScript Fetch Examples](#javascript-fetch-examples)
+- [Troubleshooting](#troubleshooting)
+- [Related Documentation](#related-documentation)
+
+## Introduction
+This guide provides accurate how-tos for networking agents in the hello-dave project. Agent communication uses WebSocket servers for real-time interaction, primarily through the CodeServer setup. The CLI entrypoint is `bin/dave.js` (or `node bin/dave.js`), with flags like `--serve` (for starting a WebSocket server on individual agents like `code_agent.js`), `--connect` (to chain to a server), and `--ask` (for querying agents locally or remotely). Multi-agent chains are orchestrated via `agents/codeserver.sh`, which launches a PM2 cluster of interconnected agents.
+
+Networking enables specialized agents (e.g., memory_agent, todo_agent, code_agent) to collaborate by connecting to a central server, supporting complex workflows like code generation with memory and testing.
+
+## Current Howtos Files
+After the urgent fix and deletion of the inaccurate previous file:
+- The `./docs/howtos/` directory was recreated and now contains only this file: `agent-networking.md` (newly created based on real project structure).
+- No other `.md` files are present.
+
+## Overview of Agent Networking
+In hello-dave, networking is WebSocket-based:
+- **Server Mode (--serve)**: Starts a WebSocket server (e.g., on `code_agent.js`) for other agents to connect to.
+- **Client Mode (--connect)**: Agents connect to a WebSocket server (e.g., `ws://localhost:8080/ws`) to forward requests and share state.
+- **Primary Example**: `agents/codeserver.sh` spawns a central `code_agent` server and connects helper agents (todo, memory, etc.) to it, forming a multi-agent chain.
+- No standalone `--serve` on `bin/dave.js`; it's used on individual agent scripts (e.g., `node code_agent.js --serve 8080`).
+- Interactions: Use `bin/dave.js --connect ws://... --secret ...` for remote queries, or pipe inputs for one-shot actions.
+- Chaining: Outputs from connected agents (e.g., memory_agent recall) feed into the main agent via WebSocket messages.
+
+This setup is useful for scalable agent collaboration but is centered around the CodeServer pattern. For broader networking, consider extending with custom WebSocket handlers.
+
+## Setup Steps
+1. **Prerequisites**:
+   - Node.js (v18+), PM2 (`npm install -g pm2`), and project dependencies: `npm install`.
+   - Set environment: `export XAIKEY=your_xai_api_key` for Grok API access (required for local asks).
+   - Ensure ports (e.g., 8080) are free and firewall allows localhost connections.
+
+2. **Project Structure**:
+   - CLI: `bin/dave.js` for high-level commands.
+   - Agents: Individual scripts in root (e.g., `code_agent.js`, `memory_agent.js`).
+   - Orchestrator: `agents/codeserver.sh` for multi-agent setup.
+
+3. **Start a Basic Server**:
+   - Run an individual agent in server mode: `node code_agent.js --serve 8080 --secret 123 --tools javascript`.
+
+4. **Connect and Interact**:
+   - Use `bin/dave.js --connect ws://localhost:8080/ws --secret 123` for interactive mode.
+   - Or pipe: `echo "Write a function" | bin/dave.js --connect ws://localhost:8080/ws --secret 123`.
+
+## Using --serve Flag
+The `--serve` flag is supported on individual agent scripts (e.g., `code_agent.js`) to start a WebSocket server. It enables the agent to act as a hub for connected clients.
+
+### Syntax
+```
+node [agent-script].js --serve [PORT] --secret [SECRET] [--tools [TOOLSET]]
+```
+- `PORT`: WebSocket port (default 8080).
+- `SECRET`: Authentication token (min 3 chars, default '123').
+- `--tools`: Optional toolset (e.g., 'javascript' for code_agent).
+
+### Example: Serving Code Agent
+```
+node code_agent.js --serve 8080 --secret mysecret --tools javascript
+```
+Output:
+```
+Code Agent WebSocket server started at ws://localhost:8080/ws
+Waiting for connections...
+```
+The server exposes `/ws` endpoint for WebSocket connections. Connected agents can send actions like `user_request`, `user_info`, `user_reset`.
+
+## Using --connect Flag
+The `--connect` flag (on `bin/dave.js` or agent scripts) connects to a WebSocket server, enabling remote interaction or chaining.
+
+### Syntax
+```
+bin/dave.js --connect [ws://URL] --secret [SECRET]
+```
+Or on agents:
+```
+node [agent-script].js --connect [ws://URL] --secret [SECRET]
+```
+- Supports interactive mode or piped input (e.g., `echo "query" | bin/dave.js --connect ...`).
+- Actions: `user_request` (default for queries), `user_info`, `user_reset`.
+
+### Example: Connecting to CodeServer
+Interactive:
+```
+bin/dave.js --connect ws://localhost:8080/ws --secret 123
+```
+Piped:
+```
+echo "Generate code for a todo app" | bin/dave.js --connect ws://localhost:8080/ws --secret 123
+```
+This forwards the request to the connected server, leveraging any chained agents.
+
+## Multi-Agent Chains via CodeServer
+The primary multi-agent setup is via `agents/codeserver.sh`, which launches a PM2 cluster:
+- Central: `code_agent` in `--serve` mode.
+- Helpers: `todo_agent`, `memory_agent`, `readme_agent`, `npm_agent`, `docs_agent`, `test_agent` all `--connect` to the central WS.
+- Chain Flow: Input → code_agent → delegates to connected agents (e.g., memory for recall, todo for planning, test for validation) → response.
+
+This forms implicit chains, e.g., code_agent queries memory_agent for context before generating code.
+
+### Chain Example: Memory → Todo → Code
+- memory_agent stores/recalls state.
+- todo_agent manages tasks based on memory.
+- code_agent generates code from todo lists, with all connected to the same WS hub.
+
+Orchestration happens internally via WebSocket message passing.
+
+## Examples
+### Basic Server + Connect
+1. Start server:
+   ```
+   node code_agent.js --serve 8080 --secret 123
+   ```
+2. Connect interactively:
+   ```
+   bin/dave.js --connect ws://localhost:8080/ws --secret 123
+   ```
+   Type queries; responses use the code_agent's capabilities.
+
+### Remote Ask via Connect
+```
+bin/dave.js --ask --connect ws://localhost:8080/ws --secret 123
+```
+Combines local asking with remote execution.
+
+## Bash Examples from codeserver.sh
+The `agents/codeserver.sh` script is the canonical multi-agent launcher. It:
+- Validates port (1024-65535) and secret (≥3 chars).
+- Deletes old PM2 processes.
+- Spawns central `code_agent --serve`.
+- Connects helpers: todo, readme, npm, docs, test, memory.
+
+### Full Script Usage
+```
+cd hello-dave
+./agents/codeserver.sh 8080 mysecret
+```
+Output:
+```
+Starting CodeServer on port 8080 in folder 'hello-dave' ... with SECRET 'mysecret'...
+CodeServer processes spawned with prefix 'hello-dave_' and suffix _8080. Check with: pm2 list | grep 'hello-dave_8080'
+dave --connect ws://127.0.0.1:8080/ws --secret 'mysecret'
+```
+
+### Custom Bash Chain Script
+Create `start-chain.sh` (inspired by codeserver.sh):
+```bash
+#!/bin/bash
+PORT=${1:-8080}
+SECRET=${2:-123}
+
+# Start central server
+node code_agent.js --serve $PORT --secret $SECRET --tools javascript &
+SERVER_PID=$!
+
+# Connect helpers
+node memory_agent.js --connect "ws://127.0.0.1:$PORT/ws" --secret $SECRET &
+node todo_agent.js --connect "ws://127.0.0.1:$PORT/ws" --secret $SECRET &
+
+# Interact
+echo "Build a simple app" | bin/dave.js --connect "ws://127.0.0.1:$PORT/ws" --secret $SECRET
+
+# Cleanup (optional)
+# kill $SERVER_PID
+```
+Run: `chmod +x start-chain.sh && ./start-chain.sh 8080 mysecret`
+
+Use PM2 for production: `pm2 start ecosystem.config.js` (define processes similarly).
+
+## JavaScript Fetch Examples
+For programmatic chaining, use native `fetch` (Node.js 18+) to interact with WS (via WebSocket library) or HTTP endpoints if exposed. However, hello-dave uses pure WS; for fetch, assume agent servers expose REST if customized. Here's a basic WS client example using `ws` library (`npm install ws`).
+
+### JS WS Client Chain
+Create `chain-client.js`:
+```javascript
+const WebSocket = require('ws');
+
+async function connectAndChain(url, secret, input) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url);
+
+    ws.on('open', () => {
+      // Send user_request (simulates piped input)
+      ws.send(JSON.stringify({ action: 'user_request', input, secret }));
+
+      let response = '';
+      ws.on('message', (data) => {
+        const msg = JSON.parse(data);
+        if (msg.type === 'content') {
+          response += msg.content;
+          if (msg.done) {
+            ws.close();
+            resolve(response);
+          }
+        }
+      });
+
+      ws.on('error', reject);
+    });
+  });
+}
+
+// Chain: Query memory via todo, then code
+async function exampleChain() {
+  const url = 'ws://localhost:8080/ws';
+  const secret = '123';
+
+  // Step 1: Recall memory (via connected memory_agent)
+  const memory = await connectAndChain(url, secret, 'Recall last task');
+  console.log('Memory:', memory);
+
+  // Step 2: Add to todo
+  const todo = await connectAndChain(url, secret, `Add task from memory: ${memory}`);
+  console.log('Todo:', todo);
+
+  // Step 3: Generate code
+  const code = await connectAndChain(url, secret, `Generate code for: ${todo}`);
+  console.log('Code:', code);
+}
+
+exampleChain().catch(console.error);
+```
+Run: `node chain-client.js` (after starting CodeServer).
+
+Note: Actual message format matches project's `wsIO` (action: 'user_request', input).
+
+## Troubleshooting
+- **Connection Refused**: Verify server is running (`node code_agent.js --serve 8080`) and port open (`netstat -tuln | grep 8080`). Check WS URL format: `ws://localhost:8080/ws`.
+- **Secret Mismatch**: Ensure `--secret` matches on connect/serve (case-sensitive, ≥3 chars). Error: "Invalid secret".
+- **PM2 Issues**: List processes: `pm2 list | grep code_agent`. Delete: `pm2 delete hello-dave_code_agent_8080`. Restart: `pm2 restart all`.
+- **No Response in Chain**: Add logging to agents (e.g., `console.log` in handlers). Verify connections: `pm2 logs hello-dave_*_8080`.
+- **Port Conflicts**: Change port in `codeserver.sh` call. Avoid <1024 ports.
+- **WebSocket Errors**: Use `wscat` for testing: `npm install -g wscat; wscat -c ws://localhost:8080/ws` (manual auth may vary).
+- **XAIKEY Missing**: For local `--ask`, set `export XAIKEY=sk-...`.
+- **Version/Deps**: Ensure Node ≥18, `npm update`. Check agent scripts for flag support.
+
+If networking needs extend beyond CodeServer (e.g., peer-to-peer), note in TODO.md for future enhancements. For now, this covers the project's real capabilities.
+
+## Related Documentation
+- [Project README](../README.md) (CLI flags, setup).
+- [Agent Scripts](../ (list individual agents like code_agent.js)).
+- [PM2 Guide](https://pm2.keymetrics.io/docs/usage/quick-start/) (for cluster management).
+- [WebSocket in Node.js](https://nodejs.org/api/websocket.html) (low-level details).

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

@@ -0,0 +1,200 @@
+# 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

@@ -0,0 +1,200 @@
+# 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).