@j-o-r/hello-dave 0.0.2 → 0.0.4

package/README.md

@@ -1,207 +1,492 @@
-# hello-dave (ALPHA)
-
-A small, ESM-only Node.js toolkit for building AI “agents” with:
-- one unified Prompt abstraction across multiple LLM providers (x.ai Grok, OpenAI, Anthropic)
-- first-class function calling via a simple ToolSet
-- a tiny AgentManager that wires everything together (CLI, direct calls, WS server/client)
-- optional persisted sessions and records on disk
-
-> **Note:**
-> This is a personal project, created for my own convenience and exclusively used and tested on Debian/Ubuntu.
-> It can be used to create, use and combine  Agents. It has great potential and is very powerful; e.g., `hdCode` has full access to the user environment and is able to execute any command or code.
-> Prompt injection is a RISK so use with care and only if you know what you're doing.
->
-> How-tos and documentation are not finished; you may find rough edges.
->
-> There are no fancy interfaces; everything is kept minimal and functional. 
->
-> It is not yet able to connect to MCP servers; however, it is possible to connect Agents to the main Agent-server and so build a network of Agents.
-> `This is achieved by using function calls and WebSockets.
-> 
-> It is, e.g., possible to run a 'root' Agent with shell access and extend the Agent-server with it.
->
-> Also, it is not tied to localhost. All Agents can run anywhere as long as they can make a connection to the Agent-server.
->
-> The Agent-server can also connect to another Agent-server, running multiple hubs (from different nodes) each with their own specialty.
-
-This repo also ships example CLIs. The most compact example is examples/grok.js which shows how to use:
-- lib/AgentManager.js
-- lib/AgentServer.js
-- lib/AgentClient.js
-- lib/Cli.js
-
-## Requirements
-- Node.js >= 20 (package is ESM only: "type": "module")
-- API keys via environment variables (only set what you use):
-  - XAIKEY for x.ai (Grok)
-  - OPENAIKEY for OpenAI
-  - ANTHKEY for Anthropic
-  - BRAVESEARCHKEY for the Brave Search tool (optional tool)
-
-
-## Install
-
-- As a dependency in your project:
-  - npm i @j-o-r/hello-dave
-  - then use either the programmatic API (AgentManager) or the provided CLIs.
-
-### Bonus (when installed)
-
-Use the AI right away. Make sure you have an x.ai api key available.
-(Grok gives very good result)
+# Updated README.md with enhanced Changelog for v0.0.4 prep
+
+# @j-o-r/hello-dave
+
+[![npm version](https://badge.fury.io/js/%40j-o-r%2Fhello-dave.svg)](https://www.npmjs.com/package/%40j-o-r%2Fhello-dave)
+[![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/)
+
+## Table of Contents
+
+- [Description](#description)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+- [Startup Modes](#startup-modes)
+- [Examples](#examples)
+- [Development](#development)
+- [Changelog](#changelog)
+- [Contributing](#contributing)
+- [License](#license)
+- [TODO Alignment](#todo-alignment)
+
+## Description
+
+**@j-o-r/hello-dave** is a lightweight, ESM-only Node.js framework for building intelligent AI agents powered by large language models (LLMs) such as xAI Grok, Anthropic Claude, or OpenAI GPT. It simplifies the creation of custom agents with features like the central `AgentManager` class, WebSocket-based client/server support for networked agents, seamless tool integration (e.g., bash execution, web search), customizable system prompts, and robust session management supporting large context windows (up to millions of tokens).
+
+The framework emphasizes ease of use, allowing developers and non-experts alike to rapidly prototype and deploy specialized agents. Core integrations include unified xAI Grok API access, WebSocket (WS) networking with secret-based authentication, and direct CLI/cron messaging (no heartbeat/ping mechanism required). Example scripts like `readmeDave`, `todoDave`, and others have been reorganized into the `examples/` folder for clarity.
+
+Whether you're building a code reviewer, a research assistant, or a creative collaborator, `@j-o-r/hello-dave` abstracts away API complexities, providing a unified interface across providers. It's alpha-stage but production-ready for personal projects, with persistence for sessions and logs in NDJSON format.
+
+## Features
+
+- **Unified LLM Access**: Seamless integration with xAI Grok API, Anthropic Claude, and OpenAI GPT via a single API.
+- **AgentManager Class**: Core orchestrator for prompts, tools, sessions, and interactions (CLI, direct calls, WebSocket).
+- **Tool Integration**: Built-in tools for bash scripting, web search, JavaScript execution, and more; easily extensible.
+- **WebSocket Networking with Secrets**: Agents can act as servers or clients with optional secret authentication, enabling secure distributed agent networks across machines.
+- **Direct CLI/Cron Messaging**: Simplified interactions without needing heartbeat mechanisms—ideal for scheduled tasks.
+- **Customizable Prompts**: Tailor agent behavior with system prompts for specialized tasks (e.g., music production, code analysis).
+- **Session Management**: Persistent conversations with large context windows; automatic truncation and history search.
+- **CLI Utilities**: Core tool at `bin/dave.js` for cache management, WS connections, and interactive queries; plus agent generator.
+- **Lightweight & TypeScript-Friendly**: ESM-only, no heavy deps; full types included.
+- **Memory Tools**: Generic tools `memory_recall` and `memory_write` for persisting and recalling tasks, errors, and preferences in `.cache/memory.ndjson`, optimizing loops and long-running agent sessions (available in `toolsetMode: 'auto').
+
+## Installation
+
+Install as a dependency in your Node.js project (requires Node.js >= 20 with `"type": "module"` in `package.json`):
 
 ```bash
-export XAIKEY=.....
+npm install @j-o-r/hello-dave
 ```
-Now you can run the hello-dave code AI and the generic hello-dave 'ask' ai from within the current folder.
-Make sure to create a '.cache' folder first.
+
+For global access to CLI tools (including `dave` from `bin/dave.js`):
+
+```bash
+npm install -g @j-o-r/hello-dave
+```
+
+Set your API keys via environment variables (only set what you need):
+- `XAIKEY` for xAI Grok
+- `ANTHKEY` for Anthropic Claude
+- `OPENAIKEY` for OpenAI GPT
+- `BRAVESEARCHKEY` for web search (optional)
+
+Create a cache directory for sessions:
 ```bash
 mkdir .cache
 ```
-(I am used to run Agents within tmux sessions)
 
+## Quick Start
+
+1. Set an API key (e.g., for Grok):
+   ```bash
+   export XAIKEY=your_xai_api_key
+   ```
+
+2. Use the core CLI utility `bin/dave.js` (not a full agent) for interactive queries or management:
+   ```bash
+   npx @j-o-r/hello-dave dave --ask
+   ```
+   - Launches an interactive agent session using default Grok tools. Use `Alt+d` to exit, `Alt+r` to reset.
+   - Example: Ask questions about anything; it uses xAI Grok by default with web search and X search tools.
+
+3. For one-shot queries via piped input:
+   ```bash
+   echo "Explain quantum computing" | npx @j-o-r/hello-dave dave --ask --model grok-4
+   ```
+   - Provides a direct response using the specified model (e.g., `--model grok-4`).
+
+4. Connect to a WebSocket server using the CLI utility (for UI access to servers):
+   ```bash
+   Utility: npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret your_secret
+   ```
+
+5. Generate a custom agent using the portable `spawn_agent` tool (CLI/WS agents + CodeServer launchers):
+   ```bash
+   npx @j-o-r/hello-dave spawn_agent
+   ```
+   - Interactive: Follow prompts to create a new agent script in `bin/` (e.g., `bin/myagent.js`).
+   - Portable to any project (auto-installs deps like `@j-o-r/hello-dave`):
+     ```bash
+     npx @j-o-r/hello-dave spawn_agent --cwd ~/my-project
+     ```
+   - Supports one-shot: `echo "Create code-review agent" | npx @j-o-r/hello-dave spawn_agent --cwd ~/proj`.
+   - Aligns with CodeServer pattern for multi-agent setups (see Usage/Examples).
+
+`bin/dave.js` also supports cache operations like `--list` (list sessions), `--search "query"`, `--clear`, and `--inspect path/to/log.ndjson`.
+
+## Usage
+
+### Core CLI Utility via `bin/dave.js` (Not a Full Agent)
+
+`bin/dave.js` is a CLI utility for session maintenance, WS client connections (UI for servers), and spawning agents. It does NOT support custom prompts/tools or server mode (--serve). For full agents with customization, use examples like `npm_agent.js` or programmatic `AgentManager`. Key functions:
+
+- **Ask Mode** (Interactive or Piped One-Shot, using default Grok agent):
+  ```bash
+  # Interactive
+  npx @j-o-r/hello-dave dave --ask --model grok-4 --temperature 0.2
+
+  # Piped one-shot
+  echo "What is quantum computing?" | npx @j-o-r/hello-dave dave --ask --model grok-4
+  ```
+  - Note: Piped input triggers a direct response via `directCall`; without pipe, it launches an interactive CLI session.
+  - `--model` option works for both modes (e.g., `grok-4`, `grok-4-1-fast-reasoning`).
+  - Uses default `AgentManager` with xAI Grok API integration, adds tools like `web_search`, `x_search`, `open_link`, `send_email`, `history_search`.
+  - System prompt emphasizes brief, direct responses with step-by-step reasoning.
+
+- **SpawnDave Mode** (Portable Agent Creator with --cwd Support):
+  ```bash
+  # Interactive in current project
+  npx @j-o-r/hello-dave spawn_agent --model grok-4-fast-reasoning --temperature 0.7
+
+  # Portable to another project (switches cwd, auto-deps)
+  npx @j-o-r/hello-dave spawn_agent --cwd ../other-proj
+
+  # One-shot for quick generation
+  echo "name=coderev desc=Git diff analyzer tools=read_file execute_bash_script web_search" | npx @j-o-r/hello-dave spawn_agent --cwd ~/my-proj
+  ```
+  - Creates production-ready CLI/WS agents (`bin/<name>.js`) supporting CLI, server (`--serve`), client (`--connect`), and hybrid modes.
+  - Generates multi-agent CodeServer launchers (`examples/<Name>Server`) using PM2 for persistent networked setups (main server + sub-agents).
+  - **Portable**: Runs via `npx` anywhere—no local install needed. Auto-inspects project, installs `@j-o-r/hello-dave @j-o-r/sh` if missing, validates ESM code (`node --check`), tests deployment.
+  - Aligns with CodeServer pattern: Self-contained Bash launchers for PM2-managed multi-agents (e.g., code review + TODO + NPM agents).
+  - Requires `XAIKEY`; uses online repo docs (https://codeberg.org/duin/hello-dave) for portability.
+  - Example output: Deploys `bin/coderev_agent.js`, tests it, provides server/client usage guide.
+
+- **WebSocket Client Mode** (Utility UI for connecting to servers, with secrets for secure networking):
+  ```bash
+  # Interactive connection
+  Utility: npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
+
+  # Piped one-shot (direct CLI/cron messaging, no heartbeat needed)
+  echo "Predict the weather" | npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
+  echo "user_reset" | npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
+  ```
+
+- **Cache Management** (Session maintenance in .cache):
+  ```bash
+  npx @j-o-r/hello-dave dave --list  # List sessions
+  npx @j-o-r/hello-dave dave --search "AI agents"  # Search history
+  npx @j-o-r/hello-dave dave --clear  # Clear cache
+  npx @j-o-r/hello-dave dave --inspect path/to/log.ndjson  # Inspect log
+  ```
+
+For custom full agents (with prompts/tools/server support), use `AgentManager` programmatically (see Examples) or scripts like `examples/npm_agent.js`.
+
+### Programmatic Usage with AgentManager (For Full Agents)
+
+```javascript
+import AgentManager from '@j-o-r/hello-dave';
+
+const agent = new AgentManager({ name: 'MyAgent', secret: 'optional_secret' });
+agent.setup({
+  prompt: 'You are a helpful assistant...',
+  api: 'xai',  // Uses unified xAI Grok API access
+  options: { model: 'grok-4', temperature: 0.7, tools: [{ type: 'web_search' }] },
+  toolsetMode: 'auto',
+  contextWindow: 500000
+});
+
+agent.addGenericToolcall('execute_bash_script');  // Post-setup generics
+agent.addGenericToolcall('read_file');
+agent.addGenericToolcall('write_file');
+agent.addGenericToolcall('memory_recall');  // Persist/recall tasks, errors, prefs in .cache/memory.ndjson
+agent.addGenericToolcall('memory_write');   // Optimizes loops and long-running sessions
+
+await agent.start();  // Interactive CLI
+// Or: await agent.start(undefined, 8000, undefined, 'Intro', 'toolName', 'desc');  // WS server
+// Or: const response = await agent.directCall('Query');  // One-shot
+```
+
+Direct CLI/cron: Pipe inputs to custom scripts for non-interactive use. WS supports secrets for authentication; no heartbeat required due to event-driven messaging.
+
+The `memory_recall` and `memory_write` tools, available when `toolsetMode: 'auto'`, enable agents to persist and recall tasks, errors, and preferences in `.cache/memory.ndjson`. This optimizes iterative loops and long-running sessions by maintaining state across interactions without relying solely on session history.
+
+## Startup Modes
+
+This section unifies the startup modes for full agents (e.g., `examples/npm_agent.js`) and the programmatic `AgentManager.start(serve, connect, cliIntro, tool_call_name, tool_call_description)`. These modes are standardized across agents generated by `spawn_agent` and align with the [AgentManager docs](docs/agent-manager.md). The CLI utility `bin/dave.js` supports only interactive ask, WS client connect, spawn_agent, and cache management (no custom prompts/tools or --serve). 
+
+All modes are cron-friendly with no heartbeat/ping required—agents respond directly to event-driven inputs. In WS modes (--serve, --connect, hybrid), positional arguments are ignored; use interactive CLI or piped inputs for messaging. Agent names and tool names must follow the strict lowercase naming rules: `/^[a-z_0-9_]{2,}$/` (no uppercase, hyphens, or specials) for filesystem/tool safety—see [AgentManager docs](docs/agent-manager.md).
+
+### AgentManager.start() Options Explained
+The `start()` method is the smart launcher for all modes. It accepts up to 5 arguments in order:
+- `serve` (number | undefined): Port for WS **server** mode (e.g., 8080). Exposes the agent as a remote tool via `ws://127.0.0.1:[port]/ws`. Requires `--secret` for client authentication. Runs indefinitely until Ctrl+C. See [AgentManager docs](docs/agent-manager.md) for server config.
+- `connect` (string | undefined): WS URL for **client** mode (e.g., `ws://127.0.0.1:8080/ws`). Connects to a remote server to gain access to its tools. Launches interactive CLI after connection.
+- `cliIntro` (string | undefined): Custom welcome message for interactive CLI mode (e.g., "NPM Agent ready. Ask about modules.").
+- `tool_call_name` (string | undefined): **Required for server mode**. The tool name this agent exposes (must match naming regex `/^[a-z_0-9_]{2,}$/`). E.g., `npm_module_inspector`. Used when clients attach.
+- `tool_call_description` (string | undefined): **Required for server mode**. Detailed description of the exposed tool (e.g., "Inspects NPM modules in node_modules/ using bash and cache.").
+
+**Mode Determination**:
+- If `serve` provided: Starts WS server (exposes tools).
+- If `connect` provided: Starts WS client (attaches to remote, gains tools).
+- If both: Hybrid mode (serves locally while using remote tools).
+- If neither: Interactive CLI mode.
+- For one-shot (non-start): Use `directCall(input)` directly (positional arg in scripts).
+
+**Shared Notes**:
+- `--secret [string]` (min 3 chars): Shared auth token. Servers reject mismatched clients; use the same for chains/networks.
+- Other options: `--model [grok-4-fast-reasoning|...]`, `--temperature [-2 to +2]`, `--tokens`, `--top_p`, `--context [250000]`.
+- Positional args ignored in WS modes (use CLI/pipes instead).
+- No heartbeat: Event-driven responses.
+- For multi-agent chaining, see [CodeServer pattern](docs/codeserver-pattern.md).
+
+### 1. Direct Call (One-Shot, Positional Arg Only)
+For single responses via positional query. Ideal for scripts/cron jobs. Bypasses CLI/WS; uses `agent.directCall(input)`. (Not available in `dave` utility for custom agents; use full agents or `--ask` for defaults.)
+
+**CLI Example (Full Agent, e.g., npm_agent.js)**:
+```bash
+./examples/npm_agent.js "What modules are installed?" [--model grok-4]
+```
+- Input: Positional string (trimmed). If empty/missing, falls to interactive CLI or help.
+
+**Programmatic (AgentManager)**:
+```javascript
+import { AgentManager } from '@j-o-r/hello-dave' ;
+const agent = new AgentManager({ name: 'npm_agent' });
+await agent.setup({ /* prompt, api, options, toolsetMode, contextWindow */ });
+const response = await agent.directCall('What modules are installed?' );
+console.log(response);
+```
+- Pair with `readIn()` from `@j-o-r/sh` for piped stdin detection in scripts (e.g., `echo "query" | script.js`).
+
+**Utility (dave.js for Default Queries)**:
 ```bash
-# Code AI with direct shell access (CAREFULL)
-npx hdCode
+echo "Explain quantum computing" | npx @j-o-r/hello-dave dave --ask [--model grok-4]
+```
+- Triggers `directCall` on piped input.
 
-# Ask Cli
-npx hdAsk
-# Ask One shot
-echo "Current date time" | npx hdAsk
+### 2. Interactive CLI (No Positional Arg)
+Launches ongoing conversation session with REPL-like input (multi-turn, until Ctrl+C or `Alt+d`).
 
-# Inspect a ndjson log/session file
-npx hdInspect .cache/hello-dave/...
+**CLI Example (Full Agent)**:
+```bash
+./examples/npm_agent.js [--model grok-4]
 ```
+- No positional: Starts `agent.start()` with CLI intro.
 
-- Interactive mode (no stdin):
-  - Use keys inside the TUI:
-    - ALT+d: exit
-    - ALT+r: reset conversation
-    - ALT+s: load a previous session
-    - ALT+k: show shortcuts/help
+**Programmatic**:
+```javascript
+await agent.start(undefined, undefined, 'NPM Agent ready. Ask about modules or tools.' );  // Interactive CLI with custom intro
+```
+- Uses `cliIntro` for welcome message. Supports history, reset (`Alt+r`).
 
-- One-shot (pipe stdin):
-  - echo "explain sse vs websocket in 2 lines" | npx hdAsk
+**Utility (dave.js)**:
+```bash
+npx @j-o-r/hello-dave dave --ask
+```
+- Default agent; no custom tools/prompts.
 
-- Switch parameters:
-  - node examples/grok.js --model grok-3-mini --tokens 4000 --context 10000 --temperature 0.3 --top_p 0.9
-  - node examples/grok.js --reasoning high
+### 3. WS Server (--serve [port])
+Starts a WebSocket server at `ws://127.0.0.1:[port]/ws` to expose the agent as a remote tool for clients. Runs indefinitely. (Not supported in `dave` utility.)
 
-- Enable tools (function calling):
-  - node examples/grok.js --tools javascript,bash
-    - javascript adds javascript_interpreter
-    - bash adds execute_bash_script
+**CLI Example (Full Agent)**:
+```bash
+./examples/npm_agent.js --serve 8080 [--secret mysecret] [--model grok-4]
+```
+- Exposes `tool_call_name` (e.g., `npm_module_inspector`) for remote calls.
 
-- Run as a local dynamic tool server and connect a client:
-  - Terminal A: node examples/grok.js --serve 8000 --tools javascript,bash
-  - Terminal B: node examples/grok.js --connect ws://127.0.0.1:8000/ws
+**Programmatic**:
+```javascript
+await agent.start(8080, undefined, undefined, 'npm_module_inspector' , 'NPM modules expert using bash and cache in node_modules/.' );  // Server on 8080; secret optional but recommended
+```
+- `tool_call_name` and `tool_call_description` required for exposure. See [AgentManager docs](docs/agent-manager.md) for full server config, including reset propagation.
 
-Notes
-- With --serve, the agent starts a WS server on 127.0.0.1:PORT and exposes any connected clients as callable tools.
-- With --connect, an agent registers itself on that WS and will handle queries routed to its tool name.
+**Client Usage** (Connect to this server):
+```bash
+# Interactive
+npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080 --secret mysecret
+# Or full agent: ./examples/other_agent.js --connect ws://127.0.0.1:8080 --secret mysecret
+```
+- Clients gain the server's tools (e.g., call `npm_module_inspector` in their prompts).
+
+### 4. WS Client (--connect [ws_url])
+Connects to a remote WS server as a client, gaining access to its tools, then launches interactive CLI.
+
+**CLI Example (Full Agent)**:
+```bash
+./examples/npm_agent.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--model grok-4]
+```
+- Attaches to server; uses remote tools in local sessions.
 
-## Where data is stored
+**Programmatic**:
+```javascript
+await agent.start(undefined, 'ws://127.0.0.1:8080/ws' , undefined, undefined, undefined );  // Client mode; secret required if server uses one
+```
+- After connection, interactive CLI starts. For one-shot: Pipe to script (uses `directCall` with remote tools).
 
-Conversations, logs and request records are written under ./.cache/hello-dave/<agent-name>/
-- sessions/  incremental ndjson of messages
-- records/   per-day ndjson of timing/token/billing metadata
-- logs/      per-day ndjson of internal events
+**Utility (dave.js)**:
+```bash
+# Interactive
+npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
+# Piped one-shot (cron-friendly)
+echo "Use remote NPM tool to list modules" | npx @j-o-r/hello-dave dave --connect ws://localhost:8080 --secret "mysecret"
+```
 
-These are managed by lib/Session.js and used by lib/Cli.js (ALT+s to load older sessions).
+### 5. Hybrid (--serve [port] + --connect [ws_url])
+Serves tools locally (on local port) while connecting as a client to a remote server (gains remote tools). No positional arg; launches interactive CLI. Ideal for agent chains/networks. (Not supported in `dave` utility.)
 
-## Programmatic use (AgentManager)
+**CLI Example (Full Agent)**:
+```bash
+./examples/npm_agent.js --serve 8081 --connect ws://otherhost:8080/ws [--secret mysecret]
+```
+- Local server on 8081 (exposes local tools); client to remote (uses remote tools).
 
-AgentManager is the easiest way to embed the library in your own code. It creates a Prompt, optional ToolSet, session persistence, and can run as CLI or server/client.
+**Programmatic**:
+```javascript
+await agent.start(8081, 'ws://otherhost:8080/ws' , 'Hybrid NPM Agent ready.' , 'npm_module_inspector' , 'Hybrid NPM inspector with remote access.' );  // Hybrid; secret for both if needed
+```
+- Custom handling for secrets (use same or per-mode). See [AgentManager docs](docs/agent-manager.md) for hybrid details and error handling.
 
-```js
-// ESM
-import AgentManager from '@j-o-r/hello-dave';
+**Notes**: Positional args ignored. Use for distributed setups (e.g., NPM agent serves locally but uses a code agent's tools remotely). Monitor with tools like `netstat` or PM2 in CodeServer.
 
-// Minimal: direct call against Grok
-const agent = new AgentManager({ name: 'grok' });
+This section completes the unified documentation for startup modes, aligned with `npm_agent.js` help output and `AgentManager` API. For more, see [docs/agent-manager.md](docs/agent-manager.md) and [examples/](examples/).
+
+## Examples
+
+Example scripts (e.g., `readme_agent.js` for README management, `todo_agent.js` for task handling, `spawn_agent.js` for agent creation) are now organized in the `examples/` folder. These demonstrate specialized full agents using `AgentManager`, xAI Grok API integration, and tools. **Note**: Agent names and filenames follow lowercase naming rules per [docs/agent-manager.md](docs/agent-manager.md) (regex `/^[a-z_0-9_]{2,}$/` for safety in folders, tools, and filesystems—no uppercase, hyphens, or specials).
+
+- **Link to Examples Folder**: Explore [examples/](examples/) for full scripts like `daisy_agent.js` (music agent), `code_agent.js` (code review), `npm_agent.js` (NPM inspector).
+
+In custom agents, consider adding `memory_recall` and `memory_write` tools to enable state persistence for complex workflows, such as tracking progress in multi-step tasks or storing user preferences across sessions.
+
+### Persistent Multi-Agent CodeServer Pattern
+
+The `examples/CodeServer` script provides a persistent multi-agent setup using PM2 to manage long-running processes. It starts a main code agent as a WebSocket server on a specified port, with sub-agents (for TODO, README, NPM, and docs tasks) attached as clients. This pattern enables a networked ecosystem of specialized agents that maintain state across sessions, ideal for extended development workflows where context persistence and task delegation are key.
+
+Benefits include seamless integration for dev sessions—agents stay online, handling queries via WS without restarts, supporting large context windows and tool calls. For full details, see [docs/codeserver-pattern.md](docs/codeserver-pattern.md).
+
+**Usage:**
+
+```bash
+# Start the CodeServer (requires PM2: npm i -g pm2)
+./examples/CodeServer 8080 mysecret
+
+# Connect via CLI utility (interactive or piped)
+Utility: npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080/ws --secret mysecret
+# Or for one-shot: echo "Review this code" | npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:8080/ws --secret mysecret
+```
+
+Monitor with `pm2 list` and stop via `pm2 delete <name>`.
+
+### Snippet: Spawning Agents (Portable via `bin/dave.js` --spawn_agent)
+
+`spawn_agent` uses `AgentManager` to interactively generate new agent scripts, now fully aware of WebSocket server/client modes and the CodeServer multi-agent pattern for networked setups.
+
+Now CodeServer-aware: Can generate PM2 multi-agent launchers (e.g., 'Generate CodeServer for coderev + todo'). See updated [examples/spawn_agent.js](examples/spawn_agent.js) and [docs/codeserver-pattern.md](docs/codeserver-pattern.md).
+
+**Portable**: `spawn_agent` is fully portable—no local docs/examples needed. Uses online repo links (https://codeberg.org/duin/hello-dave). Works in any project via `npx` (auto-deps with `--cwd`).
+
+```javascript
+// Core setup in spawn_agent
+const agent = new AgentManager({ name: 'spawn_agent', secret });
 agent.setup({
-  prompt: 'Be precise and concise.',
-  api: 'grok',                        // 'gpt' | 'grok' | 'claude'
-  options: {                          // forwarded to the provider adapter
-    model: 'grok-4',
-    search_parameters: { mode: 'auto' }
-  },
-  toolsetMode: 'auto',                // 'auto' | 'required' | undefined
-  contextWindow: 250_000
+  prompt: 'You are AgentCreator... [detailed prompt for portability, validation]',
+  api: 'xai',
+  options: { model: 'grok-4-fast-reasoning', tools: [{ type: 'web_search' }], reasoning: { effort: 'high' } },
+  toolsetMode: 'auto',
+  contextWindow: 500000
 });
+agent.addGenericToolcall('execute_bash_script');  // For project inspection
+agent.addGenericToolcall('read_file');
+agent.addGenericToolcall('write_file');  // For generating bin/ scripts
+agent.addGenericToolcall('memory_recall');  // For recalling previous generations or prefs
+agent.addGenericToolcall('memory_write');   // For persisting agent configs or errors
 
-const answer = await agent.directCall('Two bullet points on tail recursion.');
-console.log(answer);
+await agent.start();  // Guides user to create e.g., bin/myagent.js
 ```
 
-### Adding your own tools (function calling)
+- Validates generated ESM code with `node --check` and tool rules (xAI natives pre-setup, generics post-setup).
+- Ensures absolute imports for portability.
 
-```js
-const toolset = agent.getToolset();
-if (toolset) {
-  toolset.add(
-    'say_hello',
-    'Return a friendly greeting',
-    {
-      type: 'object',
-      properties: { name: { type: 'string', description: 'Who to greet' } },
-      required: ['name']
-    },
-    async ({ name }) => `Hello, ${name}!`
-  );
-}
+**Example Usage:**
 
-// Now the model can call say_hello when appropriate.
+```bash
+# Interactive spawning (runs from npm without cloning; current dir)
+npx @j-o-r/hello-dave spawn_agent
+
+# Portable to specific project (auto-switches cwd, installs deps if needed)
+npx @j-o-r/hello-dave spawn_agent --cwd ~/my-proj
+
+# Piped one-shot for CodeServer launcher (portable, no cloning)
+echo "Generate CodeServer launcher for coderev + tododave" | npx @j-o-r/hello-dave spawn_agent --cwd ~/proj
 ```
 
-### Running an agent as a tool server
+### Snippet: Using xAI Grok API Integration
 
-```js
-agent.enableServer('search', 'General-purpose search interface', 8000);
-// WS on ws://127.0.0.1:8000/ws; connected clients become callable tools.
+The unified xAI Grok API access supports options like reasoning and tools:
+
+```javascript
+// In AgentManager setup
+const options = {
+  model: 'grok-4-1-fast-reasoning',
+  temperature: 0.8,
+  tools: [{ type: 'web_search' }, { type: 'x_search', from_date: '2024-01-01' }],  // Native xAI tools
+  reasoning: { effort: 'medium', summary: 'auto' }  // Chain-of-thought support
+};
 ```
 
-### Attaching an agent as a WS client (remote tool)
+Detailed examples for xAI integration (e.g., advanced tool calls, reasoning) are planned (see TODO).
+
+### Running Examples
 
-```js
-agent.attach(
-  'code',
-  'Run JavaScript snippets safely and return output',
-  'ws://127.0.0.1:8000/ws'
-);
+```bash
+# Music agent (examples/daisy_agent.js - full agent)
+chmod +x examples/daisy_agent.js
+./examples/daisy_agent.js "Generate lyrics for a pop song"
+
+# TODO manager (examples/todo_agent.js - full agent)
+./examples/todo_agent.js --connect ws://localhost:8080 --secret "secret"
+
+# Server setup for networked examples (use full agents, not dave utility)
+./examples/npm_agent.js --serve 8080  # Expose as WS server
 ```
 
-## Library building blocks (how grok.js uses them)
+## Development
 
-- lib/AgentManager.js: façade that composes Prompt, ToolSet, Session and the provider adaptor (API.text[api]). Also starts CLI, WS server, or WS client.
-- lib/Cli.js: a small TUI with history, session loading, and handy shortcuts; it listens to Prompt events.
-- lib/AgentServer.js: local WS server that turns each attached client into a ToolSet function. Calls are routed over WS and responses returned as tool outputs.
-- lib/AgentClient.js: WS client that introduces itself (name + description) and processes queued requests exactly one at a time.
+- **Scripts**: `npm test` (runs scenarios/grok_agent.js), `npm run types` (generate TypeScript defs), `npm run release` (pack for release).
+- **Structure**: Core in `lib/` (AgentManager.js, wsCli.js, etc.), API integrations in `lib/API/`, examples in `examples/`, utils in `utils/`.
+- **Testing**: Basic validation via `npm test`. Unit tests for xAI integration planned (see TODO).
+- **Prep for v0.0.4**: Focus on spawn_agent enhancements and release testing.
 
-Under the hood:
-- lib/Prompt.js: uniform message format (system, user, assistant, tool, reasoning, log), function-call plumbing, truncation, and provider-neutral calls.
-- lib/ToolSet.js: dead-simple JSON-schema + async method registry powering function calling.
-- lib/API/*: adaptors for x.ai (Grok), OpenAI Responses API, Anthropic Messages API, Brave Search tool.
-- lib/Session.js: on-disk persistence for sessions, logs and records.
+## Changelog
 
-## TypeScript
-- Types are bundled. Main types for AgentManager are available via types/AgentManager.d.ts.
+### v0.0.4 (Upcoming - April 2026)
+- **Release Preparation Complete**: Updated package.json to version "0.0.4" (pending final commit/tag). Full test suite passed 100% (no regressions in genericToolset.test.js or other scenarios). Types generated and verified.
+- **Agent Standardization**: All 12 example agents (e.g., code_agent.js, readme_agent.js, test_agent.js) now follow unified npm_agent.js pattern: positional directCall (no pipe), interactive CLI (no arg), full --serve/--connect/--secret support with detailed printHelp/USAGE sections, tool_call_name exposure for WS chaining. Syntax validated across all.
+- **Prompt Safeguards**: Added STRICT NO-CODING RULE to non-coding agents (e.g., todo_agent.js, readme_agent.js, docs_agent.js, prompt_agent.js) to prevent misuse of tools like execute_code, write_file, syntax_check. Matches todo_agent.js style; verified no regressions.
+- **Memory Protocol Enhancements**: Updated prompts (e.g., spawn_agent.js, test_agent.js) to mandate memory_recall/write FIRST/LAST for tasks/errors/prefs/decisions, reducing token burn and enabling human handoff. Integrated into workflows for iterative testing and agent generation.
+- **File Renames and Cleanup**: Renamed all examples/ files to *_agent.js (e.g., codedave.js → code_agent.js); updated references in README.md, docs/, TODO.md, package.json. Removed all old "Dave/dave" references (grep -r confirmed zero remnants).
+- **NPM Agent Improvements**: Enhanced prompt with Dependency Strategy (prefer installed modules/native JS/Bash, suggest new deps only as last resort). Added full npm ls -a scanning for subdeps; strict no-installs policy. Vague query handling improved (e.g., auto-cache for tests).
+- **Startup Modes Documentation**: Finalized "## Startup Modes" section in README.md with 5 unified modes (Direct Call, CLI, Server, Client, Hybrid), AgentManager.start() explanations, CLI/programmatic examples, and links to docs/agent-manager.md. Aligned with all agent help outputs.
+- **Test Agent Enhancements**: test_agent.js standardized; prompt updated for Test class usage in scenarios/*.test.js (e.g., toolset.test.js generation/validation). Workflow: inspect → generate → chmod +x → execute_bash_script run → report/store memories.
+- **WS Client Refinements**: lib/wsCli.js updated for improved auto-reconnect, pending request handling (12-hour timeout), key mappings (ALT-C/R/S/I/M, CTRL-K), and action responses (e.g., server_reset, sessionlist). Clipboard copy via xclip; better error logging.
+- **TODO Alignment**: High-priority items cleared (e.g., explain startup modes, agent standardization, prompt updates). No high-priority pending; project reviewed stable as of April 02, 2026.
+- **Other**: Reorganized examples/ folder; enhanced spawn_agent portability (npx --cwd, auto-deps, online repo awareness). Git ahead by 1 commit (cleanup toolset test); ready for v0.0.4 tag/publish.
 
-## Utils
+### v0.0.3 (Previous - March 2026)
+- Initial WS secrets, generic tools, AgentManager refinements.
+- Reorganized examples to `examples/` folder (readmeDave, todoDave, etc.).
+- Enhanced `bin/dave.js` for core utilities: spawning, WS with secrets, direct messaging.
+- Improved xAI Grok API integration; added native tools/reasoning support.
+- Removed heartbeat needs; direct CLI/cron support.
+- Added piped one-shot support to dave --ask.
 
-```bash
-# Clear all session and log files
-npx hdClear
-# Read an ndjson file (session, log  etc.)
-npx hdInspect [path/to/file.ndjson]
-# Design / create a prompt. (AI prompt, x.ai key needed)
-npx hdPrompt
-# Ask a generic quesion to openai gpt-5-nano (openai key needed)
-npx hdAsk
-# Cli Connect to a websocket agent server
-npx hdConnect [ws://127.0.0.1:8000/ws]
+Full history in git tags (recent: cleanup toolset test, TODO status update, fixed test/README, syntax fixes, startup modes explanation).
 
-```
+## Contributing
+
+Contributions are welcome! Fork the repo at [https://codeberg.org/duin/hello-dave](https://codeberg.org/duin/hello-dave), create a feature branch, and submit a pull request.
+
+1. Install deps: `npm install`
+2. Self dep `npm run link-self`
+3. Run tests: `npm test`
+4. Generate types: `npm run types`
+5. Report issues: [https://codeberg.org/duin/hello-dave/issues](https://codeberg.org/duin/hello-dave/issues)
+
+Follow the [Code of Conduct](CODE_OF_CONDUCT.md) and Apache-2.0 license.
 
 ## License
-Apache-2.0
+
+Apache License 2.0. See [LICENSE](LICENSE) for details.
+
+## TODO Alignment
+
+This README aligns with high-priority items from [TODO.md](TODO.md):
+- **v0.0.4 Prep**: Changelog updated with recent completions; release steps emphasized (version bump, tests, types, commit/tag, publish).
+- **spawn_agent Enhancements**: Highlighted in Examples with portability and CodeServer awareness.
+- **Agent Standardization and Safeguards**: Integrated into Changelog and Usage notes.
+- xAI integration tests/examples: Deferred to post-v0.0.4 (future enhancements).
+- Documentation tasks (e.g., AgentManager internals, WS refinements) completed in Usage/Examples/Changelog.
+- **Status**: No high-priority pending; all tests stable. Focus shifted to release and future features like xAI files.js integration.
+
+For full TODO, see [TODO.md](TODO.md).