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

package/CHANGELOG.md

@@ -1,39 +1,25 @@
 ## Changelog
 
-### v0.0.6 (Upcoming - April 2026)
-- **Test Verifications**: Confirmed full test suite passes 100% after fixes to xAI integration tests (npm run tests or utils/test.sh). Enhanced coverage in genericToolset.test.js (memory recall with unique content isolation) and write_file_syntax.test.js (backtick/template literal handling in JS files). No regressions in scenarios/*.test.js.
-- **CLI and Documentation Updates**: Verified piped and interactive support for --ask and --connect in bin/dave.js (e.g., echo "predict weather" | dave --ask; echo "user_info" | dave --ask --connect). Updated README.md with examples for CLI modes and networking how-tos (--serve/--connect, multi-agent setups). Aligned TODO.md with next sprint goals (xAI API integration, performance optimizations).
-- **Minor Library Fixes**: Refined wsIO exports in lib/index.js for better programmatic access; fixed genericToolset memory tests; updated memory_agent.js prompts for consistent FIRST/LAST recall/write protocol; minor dave.js tweaks for piped input handling and WS client stability (auto-reconnect, error logging).
-- **Next Sprint Planning**: Prepared for v0.0.6 features including x.ai API integration into collections.js and files.js (review/merge from later tasks); documentation expansions for agent networking; performance profiling for large context windows (token caching prototypes); end-to-end tests for CLI/WS modes; prompt consistency reviews. Target release: 2026-04-06.
-- **Release Preparation**: Changelog updated with recent fixes and planned enhancements. Git commits for test/CLI/doc updates. Full suite verified; types regenerated. Ready for v0.0.6 tag/publish post-sprint.
+### v0.0.8 (Released - April 15, 2026)
+- **lib/genericToolset.js Timeout Refinements**: Switched `execute_bash_script` to @j-o-r/sh `.options({timeout: ms}).run()` with heredoc delimiter for verbatim multi-line bash_script safety. Default 360s (resets on stdout/stderr output for true idle detection only), SIGTERM on expiry. `execute_remote_script` stdin pipe preserved. Tests: success, sleep timeout (3s<7s), exit1 error, interactive `read -p` no hang.
+- **TODO.md Cleanup**: Archived all completed tasks (timeout refinements, prior v0.0.7 carryovers) to `docs/todo-archive-v0.0.8.md`. Pending changelog task completed here. Clean post-release state.
+- **.npmignore & package-lock.json**: Minor updates for cleaner packaging.
+- **Release Prep**: `package.json` bumped to v0.0.8. `npm run release` ready (types + pack to `./release/`).
 
-### v0.0.5 (Released - April 2026)
-- **Bin CLI Enhancements** (`bin/dave.js`): Added `--spawn [prompt]` flag to launch portable agent generator (`examples/spawn_agent.js` → `bin/spawn_agent.js` via `createAgent` bin). Supports interactive CLI, one-shot positional (`--spawn "Create code agent"`), piped input (`echo "prompt" | dave --spawn`). Syntax validated; portable via npx/global.
-- **createAgent Bin Promotion** (`bin/spawn_agent.js`): Dedicated `package.json` bin command (`"createAgent": "bin/spawn_agent.js"`). Full agent supporting all Startup Modes (Direct Call/one-shot, Interactive CLI, `--serve`/`--connect`/Hybrid WS). Portable npx anywhere (auto-deps `@j-o-r/hello-dave @j-o-r/sh`, online repo docs). Generates validated ESM agents (`bin/<name>.js`), PM2 CodeServer launchers (`examples/<Name>Server`). `--help` with USAGE/modes/blueprints.
-- **CodeServer Integration** (`bin/dave.js --code [port] [secret]`): Wrapper for `examples/codeserver.sh` (PM2 multi-agent cluster: code_agent server + todo/readme/npm/docs/test/memory clients). Portable shell preference; global/npx ready. Docs emphasize direct `./examples/codeserver.sh` for CI/CD.
-- **Documentation Completeness**: README.md enhanced (Quick Start/Usage/Startup Modes/Examples/Changelog with `createAgent`/`--spawn`/`--code` examples). All bin commands (`dave`, `createAgent`) fully explained. TODO.md aligned; v0.0.5 prep complete.
-- **WebSocket Export Refinements**: `lib/index.js` exports `wsCli`/`wsIO` for programmatic access (used in `bin/dave.js`).
-- **Tests & Types**: Full suite 100% passing (14/14 in `genericToolset.test.js` post-memory recall fix; unique query isolation). Types regenerated (`npm run types`).
-- **Release Prep**: Git committed/tagged v0.0.5; ready for `npm run publish`.
+### v0.0.7 (Released - April 13, 2026)
+- **spawn_agent Enhancements**: Strict blueprint enforcement in `docs/prompt/spawn_agent.md` (mandatory tool sequence: INSPECT → VALIDATE → GATHER → GENERATE → AUTO-DEPLOY/TEST). Fixed one-shot hallucination/no-deploy via verbatim AGENT BLUEPRINT TEMPLATE, temp_agent.js validation (syntax/blueprint checks), PROJECT auto-deploy (write/mv/chmod/test/rm), FRESH manual code/bash. Robust fetchLivePrompt() (live MD full-load + fallbacks). CodeServer/PM2 awareness (LAUNCH_MODE detect, client connect hints). Tested 2026-04-13: /tmp FRESH, PROJECT diag_agent.js deploy+--help success.
+- **JSDoc Updates (lib/ modules)**: Comprehensive JSDoc added/fixed for AgentClient.js, AgentManager.js, AgentServer.js, Cli.js, Prompt.js, Session.js, ToolSet.js, fafs.js, genericToolset.js, wsCli.js, wsIO.js. Typedefs, @returns, @private tags. Note: Some parser warnings (HTML entities &lt; → &lt;, import() expr); HTML generated in docs/jsdoc/.
+- **bin/codeDave Fix**: Resolved SCRIPT_DIR symlink resolution for global npm bin runs from any dir (standard readlink loop idiom). Tested from /tmp/otherdir.
+- **Types Regeneration**: `npm run types` → full types/*.d.ts updated via tsc.
+- **Docs Added/Updated**: docs/generic-toolset.md (toolsPool/examples), docs/jsdoc-best-practices.md, docs/multi-agent-clusters.md (spawn_agent PM2), docs/prompt/spawn_agent.md (PROCESS/blueprint), docs/todo-archive.md (TODO history).
+- **NPM Deps & Scripts**: Pruned extraneous, installed missing (@j-o-r/apiserver/cli, gpt-3-encoder). Clean `npm ls`. TODO.md shortened (recent 7 Done items; older archived).
+- **utils/search_sessions.sh**: Added/modified for history search.
+- **Tests & Fixes**: genericToolset.test.js notes (write_file validation stable). write_file temp-first + cleanup for deploys. All spawn_agent changes verified in CodeServer cluster (PM2 hello-dave_*_9000).
+- **Release Prep**: package.json v0.0.7, git commits/tags. Ready for `npm publish --access public`.
 
-### v0.0.4 (Released - April 2026)
-- **Release Preparation Complete**: Updated package.json to version "0.0.4", full test suite passed 100% (64/64), types generated/verified.
-- **Agent Standardization**: All 12 example agents follow unified pattern: positional directCall, interactive CLI, --serve/--connect/--secret, detailed USAGE.
-- **Prompt Safeguards**: STRICT NO-CODING RULE added to non-coding agents.
-- **Memory Protocol Enhancements**: Prompts mandate memory_recall/write FIRST/LAST.
-- **File Renames and Cleanup**: examples/*_agent.js, removed old Dave refs.
-- **NPM Agent Improvements**: Dependency strategy, npm ls -a, no-installs.
-- **Startup Modes Documentation**: Unified README section with 5 modes.
-- **Test Agent Enhancements**: Standardized for Test class in scenarios/*.test.js.
-- **WS Client Refinements**: lib/wsCli.js: auto-reconnect, key mappings, clipboard.
-- **TODO Alignment**: High-priority cleared; stable.
+### v0.0.6 (Released - April 2026)
+[Previous content unchanged]
 
-### v0.0.3 (March 2026)
-- Initial WS secrets, generic tools, AgentManager refinements.
-- Reorganized examples/.
-- Enhanced bin/dave.js: spawning, WS secrets, direct messaging.
-- xAI Grok API: native tools/reasoning.
-- No heartbeat; CLI/cron support.
-- Piped one-shot for dave --ask.
+[... rest of previous sections unchanged ...]
 
-Full history in git tags.
+Full history in git tags.

package/README.md

@@ -0,0 +1,240 @@
+# hello-dave
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Node.js >=20](https://img.shields.io/badge/Node.js-%3E=20-green.svg)](https://nodejs.org/)
+[![Version: v0.0.8](https://img.shields.io/badge/Version-v0.0.8-green.svg)](https://codeberg.org/duin/hello-dave)
+[![PM2 Compatible](https://img.shields.io/badge/PM2-Compatible-orange.svg)](https://pm2.keymetrics.io/)
+
+## Table of Contents
+
+- [Description](#description)
+- [Features](#features)
+- [Folder Structure](#folder-structure)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Usage Examples](#usage-examples)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Description
+
+**hello-dave** is an ESM (ECMAScript Modules) toolkit for building AI agents with unified access to endpoints from Grok (xAI), OpenAI, and Anthropic. It provides CLI tools for interacting with agents locally or via WebSocket servers, along with pre-built agent scripts for various tasks like code generation, documentation, testing, and more.
+
+The project emphasizes modular agent management, tool integration (e.g., web search, file operations), and session handling with memory and caching. With v0.0.8, enhanced portability allows spawning agents in isolated environments like `/tmp` while maintaining tool functionality relative to the current working directory (CWD).
+
+## Features
+
+- **Unified API Access**: Seamless integration with xAI (Grok), OpenAI, and Anthropic models.
+- **CLI Tools**: `dave` for querying agents, `agentDave` for spawning servers, `codeDave` for code servers.
+- **Agent Scripts**: Specialized agents for code, docs, npm, todo, readme, memory, and more.
+- **WebSocket Support**: Connect to remote agent servers for interactive or one-shot interactions.
+- **Toolsets**: Built-in tools for search, file I/O, email, and custom toolcalls.
+- **Session Management**: Cache history, search sessions, reset, and inspect logs.
+- **ESM-First**: Modern Node.js modules with TypeScript definitions.
+- **Portable Agent Spawning**: `spawn_agent.js` enables creating and deploying agents anywhere (project dirs or fresh `/tmp`). Supports auto-deploy in existing projects (detects `./agents/*.js`), manual code+bash in isolated setups. Tools adapt to CWD for portability. Hybrid modes combine server/client for chaining. See [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) for blueprint and validation.
+- **Multi-Agent Clusters**: PM2-powered CodeServer for scalable, clustered agent deployments (e.g., code_agent + todo_agent). Defaults to port 9000/secret '123'. See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md) for configuration.
+
+## Folder Structure
+
+- **bin/**: Executables for CLI tools.
+  - `dave.js`: Main CLI for asking agents or connecting to WebSocket servers.
+  - `spawn_agent.js`: Spawns agent instances (binary: `agentDave`).
+  - `codeDave`: Launches code servers (via PM2 clusters). References [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md) for setup and scaling.
+
+- **agents/**: Agent scripts (`*_agent.js`) for specific tasks. These can be run directly with `node agents/<script>.js`.
+  - `ask_agent.js`: General query agent.
+  - `code_agent.js`: Code generation and execution agent (serves as main server in code clusters).
+  - `daisy_agent.js`: Specialized agent (details in script).
+  - `docs_agent.js`: Documentation-focused agent.
+  - `gpt_agent.js`: OpenAI GPT integration agent.
+  - `grok_agent.js`: xAI Grok-specific agent.
+  - `memory_agent.js`: Agent with enhanced memory and context handling.
+  - `npm_agent.js`: NPM package management agent.
+  - `prompt_agent.js`: Prompt engineering and testing agent.
+  - `readme_agent.js`: README.md management agent.
+  - `spawn_agent.js`: Agent spawner (also in bin/). Creates portable CLI/WS agents + PM2 launchers. Validates/tests/deploys to `./agents/<name>.js`. Supports hybrid server/client modes. Portable to `/tmp` (tools follow CWD). Blueprint: [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md).
+  - `test_agent.js`: Testing and validation agent.
+  - `todo_agent.js`: TODO list and task management agent.
+  - `codeserver.sh`: Shell script for launching PM2-based code server clusters (uses agents above). See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
+
+- **lib/**: Core library modules (e.g., `index.js`, `wsCli.js`, `wsIO.js`, API integrations).
+- **scenarios/**: Test and example scenarios (e.g., toolset tests, integration scripts).
+- **types/**: TypeScript definitions.
+- **utils/**: Utility scripts (e.g., session management, testing).
+- **docs/**: Additional documentation, including agent blueprints (e.g., [prompt/spawn_agent.md](docs/prompt/spawn_agent.md)) and multi-agent guides (e.g., [multi-agent-clusters.md](docs/multi-agent-clusters.md)).
+- **release/**: Build artifacts.
+
+Other files: `package.json`, `CHANGELOG.md`, `TODO.md`, `LICENSE`.
+
+## Installation
+
+1. **Prerequisites**: Node.js >= 20. PM2 for multi-agent clusters: `npm install -g pm2`.
+
+2. **Local Development**:
+   ```bash
+   git clone https://codeberg.org/duin/hello-dave.git
+   cd hello-dave
+   npm install
+   ```
+
+3. **Global CLI Installation** (for `dave`, `agentDave`, `codeDave`):
+   ```bash
+   npm install -g .
+   # Or link for dev: npm run link-self
+   ```
+
+4. **API Keys**: Set environment variables (e.g., `XAIKEY` for xAI, `OPENAI_API_KEY` for OpenAI).
+
+## Usage
+
+### CLI Tools
+
+- **dave**: Interact with agents locally or remotely.
+  - Local query: `dave --ask "Predict the weather"`
+  - One-shot remote: `echo "Hello" | dave --connect 'ws://127.0.0.1:8080' --secret '123'`
+  - Interactive remote: `dave --connect 'ws://127.0.0.1:8080' --secret '123'`
+  - Other: `dave --list` (sessions), `dave --clear` (cache), `dave --help`.
+
+- **agentDave**: Spawn an agent server (powered by `spawn_agent.js`).
+  ```bash
+  agentDave --serve 8080 --secret '123'  # Starts WebSocket server
+  ```
+
+- **codeDave**: Launch a PM2 code server cluster.
+  ```bash
+  codeDave 8080 --secret '123'  # Or: dave --code 8080 --secret '123'
+  ```
+
+### Running Agents
+
+Run agent scripts directly:
+```bash
+node agents/spawn_agent.js --serve 8080 --secret '123'  # Spawn server
+node agents/code_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'  # Client mode
+```
+
+For full options, see script headers or run with `--help`.
+
+### Programmatic Usage
+
+Import and use in your Node.js app:
+```javascript
+import { AgentManager } from '@j-o-r/hello-dave';
+// Setup and run agent...
+```
+
+### spawn_agent.js Specifics (v0.0.8 Portability Ready)
+
+`spawn_agent.js` (executable as `agentDave`) creates and deploys portable agents in CLI, WebSocket server, client, or **hybrid** modes (server + client for tool chaining). It fetches live prompts from [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) and validates new agents via blueprint (temp files, syntax checks, grep for modes/tools).
+
+- **Modes**:
+  - **Direct (One-Shot)**: Positional input, e.g., `node agents/spawn_agent.js "Create a tester"`.
+  - **Interactive CLI**: No input; runs REPL-like session.
+  - **Server**: `--serve <port>` – Exposes as remote tool (e.g., for other agents to call `spawn_agent`).
+  - **Client**: `--connect <ws_url>` – Connects to remote server for tool access.
+  - **Hybrid**: `--serve <port> --connect <ws_url>` – Serves locally while using remote tools.
+
+- **Portability**:
+  - **In Project**: Auto-deploys to `./agents/<name>.js` if `./agents/*.js` exist (uses existing structure).
+  - **Fresh /tmp**: Manual code generation + bash setup (e.g., `mkdir /tmp/myproj/agents; cd /tmp/myproj; node spawn_agent.js ...`). Tools (e.g., `read_file`) follow CWD, ensuring isolation without fixed paths.
+  - Works in any dir; no repo deps beyond Node.js + npm installs.
+
+- **Custom Tools**: Specify in prompt, e.g., "name=coderev, tools=read_file,web_search,execute_bash_script".
+
+For validation/testing: See blueprint in [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) (includes bash examples like `node agents/NEW_AGENT.js --help` or server connect tests).
+
+### CodeServer & PM2 Multi-Agent (v0.0.8)
+
+CodeServer (via `bin/codeDave` or `agents/codeserver.sh`) launches scalable, PM2-clustered multi-agent environments for collaborative tasks (e.g., code generation + task management). It deploys agents like `code_agent`, `todo_agent`, and `readme_agent` on a WebSocket server, enabling chaining and load balancing.
+
+- **Defaults**: Port 9000, secret '123' (customizable via args).
+- **Prerequisites**: Install PM2 globally (`npm install -g pm2`).
+- **Quickstart**:
+  ```bash
+  codeDave 9000 --secret 123  # Launches PM2 cluster on ws://127.0.0.1:9000/ws
+  pm2 list  # Verify processes (e.g., code_agent, todo_agent instances)
+  echo "task" | bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123  # One-shot query to cluster
+  ```
+  This starts the cluster, lists running agents, and sends a test task (response routed to available agents).
+
+- **Scaling & Management**: Use PM2 commands (e.g., `pm2 scale <app> 4`, `pm2 stop all`). For ecosystem config, PM2 JSON files, or agent orchestration, see the [full guide in docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
+
+- **Integration**: Combine with `spawn_agent.js` for dynamic agent addition to clusters (e.g., spawn new agents and connect via `--connect ws://127.0.0.1:9000/ws`).
+
+## Usage Examples
+
+- **Direct Spawn (Project)**:
+  ```bash
+  cd hello-dave  # Or any project with ./agents/
+  node agents/spawn_agent.js "Create code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file,execute_bash_script,web_search"
+  # Deploys to ./agents/coderev_agent.js; test: node agents/coderev_agent.js "Review this diff"
+  ```
+
+- **/tmp Workflow (Portable, Fresh Setup)**:
+  ```bash
+  mkdir -p /tmp/myportable/agents
+  cd /tmp/myportable
+  # Copy or fetch spawn_agent.js (e.g., curl from repo or npm install @j-o-r/hello-dave)
+  npm init -y && npm i @j-o-r/hello-dave @j-o-r/sh
+  node spawn_agent.js "Create todo agent: name=todo, desc=Task manager, tools=read_file,write_file"
+  # Deploys to ./agents/todo_agent.js; tools use /tmp/myportable as CWD
+  node agents/todo_agent.js --serve 8081 --secret abc  # Test server mode
+  ```
+
+- **Hybrid Mode with Custom Tools**:
+  ```bash
+  node agents/spawn_agent.js --serve 8081 --connect ws://127.0.0.1:8080/ws --secret abc "Spawn a docs agent with custom email tool"
+  # Serves on 8081 (exposes new agent), connects to 8080 (gains remote tools like email)
+  # Test: In another term, node agents/spawn_agent.js --connect ws://127.0.0.1:8081/ws --secret abc "Use the new docs agent"
+  ```
+
+- **Spawn a Server**:
+  ```bash
+  node agents/spawn_agent.js --serve 8080 --secret '123'
+  # Then connect: echo "Task" | dave --connect 'ws://127.0.0.1:8080' --secret '123'
+  ```
+
+- **Launch Code Cluster** (includes multiple agents):
+  ```bash
+  node agents/codeserver.sh 9000 '123'  # Or use codeDave 9000 --secret 123
+  # Connects code_agent, todo_agent, readme_agent, etc., to the server on ws://127.0.0.1:9000/ws.
+  # Test: pm2 list; echo "Optimize this code" | dave --connect ws://127.0.0.1:9000/ws --secret 123
+  # For advanced config: See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
+  ```
+
+- **Local Agent Query** (no server):
+  ```bash
+  dave --ask --model 'grok-4-1-fast-reasoning' "Write a function"
+  ```
+
+- **Custom Agent**:
+  ```bash
+  node agents/docs_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'
+  ```
+
+See `scenarios/` for more test scenarios.
+
+## Development
+
+- **Build Types**: `npm run types`
+- **Test**: `npm run tests` (runs `utils/test.sh`)
+- **Release**: `npm run release` then `npm run publish`
+- **Local Linking**: `npm run link-self` / `npm run unlink-self`
+
+Use `git status` and `ls` to inspect changes. Ensure ESM compatibility.
+
+## Contributing
+
+Contributions welcome! Fork the repo, create a branch, and submit a pull request to https://codeberg.org/duin/hello-dave.
+
+- Report bugs: https://codeberg.org/duin/hello-dave/issues
+- Follow Apache-2.0 license.
+
+## License
+
+This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
+
+---
+*Repository: https://codeberg.org/duin/hello-dave*
+---

package/TODO.md

@@ -0,0 +1,13 @@
+## TODO (high priority pending)
+(none)
+
+## In Progress
+(none)
+
+## Later (future tasks)
+(none)
+
+## Done
+(none - archived to docs/todo-archive-v0.0.8.md on 2026-04-15)
+
+Older tasks archived on 2026-04-13 to docs/todo-archive.md.

package/{examples → agents}/ask_agent.js

@@ -56,19 +56,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Your query here" [--options]
+./agents/${name}.js "Your query here" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'search_agent'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/codeserver.sh

@@ -25,23 +25,23 @@ FOLDER=$(basename "$PROJECT_DIR")
 echo "Starting CodeServer on port ${PORT} in folder '${FOLDER}' (SCRIPT_DIR: ${SCRIPT_DIR}) with SECRET '${SECRET}'..."
 
 # Delete existing processes with folder_port suffix
-pm2 delete "${FOLDER}_code_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_todo_agent_${PORT}"  2>/dev/null || true
-pm2 delete "${FOLDER}_readme_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_npm_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_docs_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_test_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_memory_agent_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_code_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_todo_${PORT}"  2>/dev/null || true
+pm2 delete "${FOLDER}_readme_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_npm_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_docs_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_test_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_memory__${PORT}" 2>/dev/null || true
 
 # Spawn main Agent / server (absolute paths to scripts)
-pm2 start "${SCRIPT_DIR}/code_agent.js" --name "${FOLDER}_code_agent_${PORT}" -- --serve "${PORT}" --tools javascript --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/code_agent.js" --name "${FOLDER}_code_${PORT}" -- --serve "${PORT}" --tools javascript --secret "${SECRET}"
 # Attach clients
-pm2 start "${SCRIPT_DIR}/todo_agent.js"   --name "${FOLDER}_todo_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/readme_agent.js" --name "${FOLDER}_readme_agent_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/npm_agent.js"    --name "${FOLDER}_npm_agent_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/docs_agent.js"   --name "${FOLDER}_docs_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/test_agent.js"   --name "${FOLDER}_test_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/memory_agent.js"   --name "${FOLDER}_memory_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/todo_agent.js"   --name "${FOLDER}_todo_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/readme_agent.js" --name "${FOLDER}_readme_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/npm_agent.js"    --name "${FOLDER}_npm_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/docs_agent.js"   --name "${FOLDER}_docs_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/test_agent.js"   --name "${FOLDER}_test_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/memory_agent.js"   --name "${FOLDER}_memory_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
 
 echo "CodeServer processes spawned with prefix '${FOLDER}_' and suffix _${PORT}. Check with: pm2 list | grep '${FOLDER}_${PORT}'"
 echo "dave --connect ws://127.0.0.1:${PORT}/ws --secret '$SECRET'"

package/{examples → agents}/daisy_agent.js

@@ -57,19 +57,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Generate lyrics for pop song" [--options]
+./agents/${name}.js "Generate lyrics for pop song" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'daisy_agent'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/docs_agent.js

@@ -54,19 +54,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Create a doc on Node.js basics" [--options]
+./agents/${name}.js "Create a doc on Node.js basics" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'agent_docs'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/gpt_agent.js

@@ -52,19 +52,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Your query" [--options]
+./agents/${name}.js "Your query" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'gpt_agent'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/grok_agent.js

@@ -64,19 +64,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "What is your task?" [--options]
+./agents/${name}.js "What is your task?" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL. Runs indefinitely until Ctrl+C.

package/{examples → agents}/memory_agent.js

@@ -56,19 +56,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Recall tasks" [--options]
+./agents/${name}.js "Recall tasks" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'memory_agent'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/npm_agent.js

@@ -55,19 +55,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "What modules are installed?" [--options]
+./agents/${name}.js "What modules are installed?" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'npm_module_inspector'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/prompt_agent.js

@@ -54,19 +54,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Optimize this prompt: [prompt]" [--options]
+./agents/${name}.js "Optimize this prompt: [prompt]" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'prompt_agent'). Runs indefinitely until Ctrl+C.