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

package/docs.bak.1774780058/agent-manager.md

@@ -1,167 +0,0 @@
-# AgentManager (`lib/AgentManager.js`)
-
-## Overview
-**AgentManager** is the central orchestrator class in the hello-dave framework. It manages agent lifecycle: setup (prompts, API, tools, sessions), execution modes (CLI, direct calls, WebSocket server/client), and tool integration. Designed for simplicity and extensibility, it abstracts LLM providers (`xai`, `gpt`, `claude`), `Prompt.js`, `ToolSet.js`, and `Session.js`.
-
-**Uses named exports from `lib/index.js` - NO default export.**
-
-Key Features:
-- **Modes**: Interactive CLI, one-shot `directCall`, WS **server** (expose agent as tool), **client** (attach to remote server), hybrid (server + client).
-- **Tool Handling**: Pre-configured (`toolsetMode: 'auto'`/`'required'`), generics (`addGenericToolcall`), custom `ToolSet`.
-- **Persistence**: Sessions in `.cache/[name]/` (NDJSON logs).
-- **Networking**: WS with optional `secret` auth (base64-encoded).
-- **Validation**: Strict name regex `/^[a-z_0-9_]{2,}$/`.
-- **Events**: Leverages `Prompt` events (e.g., `reset` → server resetAll).
-
-Exports: `{ AgentManager }` (named).
-
-## Agent Naming Rules ⚠️
-**CRITICAL**: The `name` (constructor) and `toolName` (in `start()`) **MUST** match regex `/^[a-z_0-9_]{2,}$/`:
-- Lowercase `a-z`, digits `0-9`, `_` **only**.
-- **Minimum 2 characters**.
-
-**Valid ✅**:
-- `myagent`
-- `chatbot`
-- `weather_agent`
-- `tool123`
-- `ws_client`
-
-**Invalid ❌ (throws `Error`)**:
-- `MyAgent` (uppercase)
-- `agent-v1` (hyphen)
-- `a` (too short)
-- `agent#tool` (`#` invalid)
-- `Agent_` (uppercase)
-
-**Why?** Safe for folders, tool names, filesystems (no specials/caps/spaces).
-
-## Quick Usage
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-
-const agent = new AgentManager({ name: 'myagent', secret: 'mysecret' });
-agent.setup({
-  prompt: 'You are a helpful coding assistant.',
-  api: 'xai',
-  options: { model: 'grok-4-fast-reasoning' },
-  toolsetMode: 'auto',
-  contextWindow: 128000
-});
-agent.addGenericToolcall('execute_bash_script');
-
-await agent.start();  // CLI mode
-// Or: await agent.directCall('Write a Bash script');  // One-shot
-// Or: await agent.start(8000);  // WS server on port 8000
-```
-
-## Constructor Options
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `name` | string | `'agent'` | **Agent ID (session folder, tool name). MUST match `/^[a-z_0-9_]{2,}$/` (lowercase a-z0-9_; ≥2 chars).** |
-| `secret` | string | `''` | WS auth (base64-encoded; optional, match server/client). |
-| `cachePath` | string | `'.cache/hello-dave'` | Session storage root. |
-
-## setup(setup) → `this` (chainable)
-Configures the agent. Must call before `start()`/`directCall()`.
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `prompt` | string | - | **Required**: System prompt. |
-| `api` | `'xai'|'gpt'|'claude'` | `'gpt'` | LLM provider (uses `lib/API/[provider]/text.js`). |
-| `options` | `XAIOptions`/`OAOptions`/etc. | `{}` | Provider-specific (model, temperature, tools, reasoning). |
-| `contextWindow` | number | `300000` | Token limit for `Prompt`. |
-| `toolsetMode` | `'auto'|'required'` | `null` | `'auto'`: Generic tools; `'required'`: Empty `ToolSet` (add manually). |
-| `debug` | boolean | `false` | Verbose logging. |
-
-Internals: Creates `Prompt`, `Session`, sets `Prompt.setAdaptor(API.text[api], toolset, options)`.
-
-## Key Methods
-| Method | Args | Returns | Description |
-|--------|------|---------|-------------|
-| `directCall(input)` | `string` | `Promise<string>` | One-shot query (via `prompt.call()`). |
-| `getPrompt()` | - | `Prompt` | Access internal `Prompt`. |
-| `getToolset()` | - | `ToolSet\|void` | Access tools. |
-| `environment()` | - | `Promise<EnvironmentInfo>` | System info (via `fafs.js/env()`). |
-| `addGenericToolcall(name)` | string (e.g., `'read_file'`) | - | Copy from `genericToolset.js` pool. Post-setup only. |
-| `start(servePort?, connectUrl?, cliIntro?, toolName?, toolDesc?)` | Mixed | `Promise<void>` | **Smart launcher**:<br>- `servePort` (num): WS **server** (**toolName** MUST match name regex or auto-gen).<br>- `connectUrl` (str, e.g. `'ws://127.0.0.1:8000/ws'`): WS **client** (toolName/desc for attachment).<br>- Neither: **CLI** mode.<br>- Both: Hybrid. |
-
-## Workflow Diagram
-```mermaid
-graph TD
-    A[New AgentManager name, secret] --> B[setup prompt, api, options, toolsetMode]
-    B --> C{start args?}
-    C -->|servePort| D[enableServer port, name, desc<br/>+ optional attach client]
-    C -->|connectUrl| E[attach client url, name, desc]
-    C -->|none| F[startCli intro]
-    D --> G[Session Loop: Prompt → API/Tools → Response]
-    E --> G
-    F --> G
-    G --> H[directCall or persist]
-```
-
-**Per-Endpoint Options**:
-- **CLI**: `start()` → `Cli` (interactive/piped). Options via `setup`.
-- **WS Server**: `start(port)` → `AgentServer` (localhost only). Exposes agent as tool (name/desc). `secret` required for clients. `prompt.on('reset')` → `server.resetAll()`.
-- **WS Client**: `start(undefined, url)` → `AgentClient`. Connects to remote server; agent callable as tool.
-- **Direct**: `directCall()` bypasses networking/CLI.
-
-## Examples
-
-### 1. Interactive CLI Agent
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-
-const agent = new AgentManager({ name: 'chatbot' });
-agent.setup({
-  prompt: 'You are a friendly chatbot.',
-  api: 'xai',
-  toolsetMode: 'auto'
-});
-await agent.start('Chatbot ready!');  // Auto-generates intro
-```
-
-### 2. WS Server (Expose as Tool)
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-
-agent.setup({ ... });
-await agent.start(8000, undefined, undefined, 'weathertool', 'Get real-time weather');
-```
-- Clients: `npx @j-o-r/hello-dave dave --connect ws://localhost:8000/ws --secret mysecret`
-
-### 3. Hybrid + Direct Call
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-
-await agent.start(8001, 'ws://other:8000/ws');  // Server on 8001 + client to other
-const resp = await agent.directCall('Hybrid query');  // Uses attached tools too
-```
-
-### 4. Custom Tools + Generics
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-
-agent.setup({ toolsetMode: 'required' });
-const ts = agent.getToolset();
-ts.add('custommath', 'Add numbers', {
-  type: 'object', properties: {a: {type: 'number'}, b: {type: 'number'}},
-  required: ['a', 'b']
-}, async ({a, b}) => a + b);
-agent.addGenericToolcall('javascript_interpreter');
-```
-
-## Advanced: Networking & Secrets
-- **Server-Client Chain**: Server A attaches to Server B → A callable from B (and vice versa if mutual).
-- **Cron/CLI Messaging**: Pipe to client: `echo 'query' | npx ... dave --connect ...`
-- **Reset**: `Prompt` emits `'reset'` → propagates to attached servers/clients.
-
-## Errors
-- No `setup()`: Throws.
-- **Invalid `name`/`toolName`: Regex `/^[a-z_0-9_]{2,}$/` fail → `Error`.**
-- No `toolset` on server: Throws.
-
-See source `lib/AgentManager.js` for full JSDoc/types. Cross-links:
-- [Prompt](./prompt-class.md)
-- [ToolSet](./toolset.md)
-- [Generic Tools](../lib/genericToolset.js)

package/docs.bak.1774780058/agent-manager.md.bak

@@ -1,137 +0,0 @@
-# AgentManager (`lib/AgentManager.js`)
-
-## Overview
-**AgentManager** is the central orchestrator class in the hello-dave framework. It manages agent lifecycle: setup (prompts, API, tools, sessions), execution modes (CLI, direct calls, WebSocket server/client), and tool integration. Designed for simplicity and extensibility, it abstracts LLM providers (`xai`, `gpt`, `claude`), `Prompt.js`, `ToolSet.js`, and `Session.js`.
-
-Key Features:
-- **Modes**: Interactive CLI, one-shot `directCall`, WS **server** (expose agent as tool), **client** (attach to remote server), hybrid (server + client).
-- **Tool Handling**: Pre-configured (`toolsetMode: 'auto'`/`'required'`), generics (`addGenericToolcall`), custom `ToolSet`.
-- **Persistence**: Sessions in `.cache/[name]/` (NDJSON logs).
-- **Networking**: WS with optional `secret` auth (base64-encoded).
-- **Validation**: Strict name regex `/^[a-z_0-9]{2,}$/`.
-- **Events**: Leverages `Prompt` events (e.g., `reset` → server resetAll).
-
-Exports: `default AgentManager`.
-
-## Quick Usage
-```javascript
-import AgentManager from '../lib/AgentManager.js';  // or '@j-o-r/hello-dave'
-
-const agent = new AgentManager({ name: 'myagent', secret: 'mysecret' });
-agent.setup({
-  prompt: 'You are a helpful coding assistant.',
-  api: 'xai',
-  options: { model: 'grok-4-fast-reasoning' },
-  toolsetMode: 'auto',
-  contextWindow: 128000
-});
-agent.addGenericToolcall('execute_bash_script');
-
-await agent.start();  // CLI mode
-// Or: await agent.directCall('Write a Bash script');  // One-shot
-// Or: await agent.start(8000);  // WS server on port 8000
-```
-
-## Constructor Options
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `name` | string | `'agent'` | Agent ID (session folder, tool name). Regex: `/^[a-z_0-9]{2,}$/`. |
-| `secret` | string | `''` | WS auth (base64-encoded; optional, match server/client). |
-| `cachePath` | string | `'.cache/hello-dave'` | Session storage root. |
-
-## setup(setup) → `this` (chainable)
-Configures the agent. Must call before `start()`/`directCall()`.
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `prompt` | string | - | **Required**: System prompt. |
-| `api` | `'xai'|'gpt'|'claude'` | `'gpt'` | LLM provider (uses `lib/API/[provider]/text.js`). |
-| `options` | `XAIOptions`/`OAOptions`/etc. | `{}` | Provider-specific (model, temperature, tools, reasoning). |
-| `contextWindow` | number | `300000` | Token limit for `Prompt`. |
-| `toolsetMode` | `'auto'|'required'` | `null` | `'auto'`: Generic tools; `'required'`: Empty `ToolSet` (add manually). |
-| `debug` | boolean | `false` | Verbose logging. |
-
-Internals: Creates `Prompt`, `Session`, sets `Prompt.setAdaptor(API.text[api], toolset, options)`.
-
-## Key Methods
-| Method | Args | Returns | Description |
-|--------|------|---------|-------------|
-| `directCall(input)` | `string` | `Promise<string>` | One-shot query (via `prompt.call()`). |
-| `getPrompt()` | - | `Prompt` | Access internal `Prompt`. |
-| `getToolset()` | - | `ToolSet\|void` | Access tools. |
-| `environment()` | - | `Promise<EnvironmentInfo>` | System info (via `fafs.js/env()`). |
-| `addGenericToolcall(name)` | string (e.g., `'read_file'`) | - | Copy from `genericToolset.js` pool. Post-setup only. |
-| `start(servePort?, connectUrl?, cliIntro?, toolName?, toolDesc?)` | Mixed | `Promise<void>` | **Smart launcher**:<br>- `servePort` (num): WS **server** (toolName/desc auto-gen).<br>- `connectUrl` (str, e.g. `'ws://127.0.0.1:8000/ws'`): WS **client** (attach as tool).<br>- Neither: **CLI** mode.<br>- Both: Hybrid server+client. |
-
-## Workflow Diagram
-```mermaid
-graph TD
-    A[New AgentManager name, secret] --> B[setup prompt, api, options, toolsetMode]
-    B --> C{start args?}
-    C -->|servePort| D[enableServer port, name, desc<br/>+ optional attach client]
-    C -->|connectUrl| E[attach client url, name, desc]
-    C -->|none| F[startCli intro]
-    D --> G[Session Loop: Prompt → API/Tools → Response]
-    E --> G
-    F --> G
-    G --> H[directCall or persist]
-```
-
-**Per-Endpoint Options**:
-- **CLI**: `start()` → `Cli` (interactive/piped). Options via `setup`.
-- **WS Server**: `start(port)` → `AgentServer` (localhost only). Exposes agent as tool (name/desc). `secret` required for clients. `prompt.on('reset')` → `server.resetAll()`.
-- **WS Client**: `start(undefined, url)` → `AgentClient`. Connects to remote server; agent callable as tool.
-- **Direct**: `directCall()` bypasses networking/CLI.
-
-## Examples
-
-### 1. Interactive CLI Agent
-```javascript
-const agent = new AgentManager({ name: 'chatbot' });
-agent.setup({
-  prompt: 'You are a friendly chatbot.',
-  api: 'xai',
-  toolsetMode: 'auto'
-});
-await agent.start('Chatbot ready!');  // Auto-generates intro
-```
-
-### 2. WS Server (Expose as Tool)
-```javascript
-agent.setup({ ... });
-await agent.start(8000, undefined, undefined, 'weatherTool', 'Get real-time weather');
-```
-- Clients: `npx @j-o-r/hello-dave dave --connect ws://localhost:8000/ws --secret mysecret`
-
-### 3. Hybrid + Direct Call
-```javascript
-await agent.start(8001, 'ws://other:8000/ws');  // Server on 8001 + client to other
-const resp = await agent.directCall('Hybrid query');  // Uses attached tools too
-```
-
-### 4. Custom Tools + Generics
-```javascript
-agent.setup({ toolsetMode: 'required' });
-const ts = agent.getToolset();
-ts.add('customMath', 'Add numbers', {
-  type: 'object', properties: {a: {type: 'number'}, b: {type: 'number'}},
-  required: ['a', 'b']
-}, async ({a, b}) => a + b);
-agent.addGenericToolcall('javascript_interpreter');
-```
-
-## Advanced: Networking & Secrets
-- **Server-Client Chain**: Server A attaches to Server B → A callable from B (and vice versa if mutual).
-- **Cron/CLI Messaging**: Pipe to client: `echo 'query' | npx ... dave --connect ...`
-- **Reset**: `Prompt` emits `'reset'` → propagates to attached servers/clients.
-
-## Errors
-- No `setup()`: Throws.
-- Invalid `name`/`toolName`: Regex fail.
-- No `toolset` on server: Throws.
-
-See source `lib/AgentManager.js` for full JSDoc/types. Cross-links:
-- [Prompt](./prompt-class.md)
-- [ToolSet](./toolset.md)
-- [Generic Tools](../lib/genericToolset.js)
-"

package/docs.bak.1774780058/agent-manager.md.bak2

@@ -1,157 +0,0 @@
-# AgentManager (`lib/AgentManager.js`)
-
-## Overview
-**AgentManager** is the central orchestrator class in the hello-dave framework. It manages agent lifecycle: setup (prompts, API, tools, sessions), execution modes (CLI, direct calls, WebSocket server/client), and tool integration. Designed for simplicity and extensibility, it abstracts LLM providers (`xai`, `gpt`, `claude`), `Prompt.js`, `ToolSet.js`, and `Session.js`.
-
-Key Features:
-- **Modes**: Interactive CLI, one-shot `directCall`, WS **server** (expose agent as tool), **client** (attach to remote server), hybrid (server + client).
-- **Tool Handling**: Pre-configured (`toolsetMode: 'auto'`/`'required'`), generics (`addGenericToolcall`), custom `ToolSet`.
-- **Persistence**: Sessions in `.cache/[name]/` (NDJSON logs).
-- **Networking**: WS with optional `secret` auth (base64-encoded).
-- **Validation**: Strict name regex `/^[a-z_0-9_]{2,}$/`.
-- **Events**: Leverages `Prompt` events (e.g., `reset` → server resetAll).
-
-Exports: `default AgentManager`.
-
-## Agent Naming Rules ⚠️
-**CRITICAL**: The `name` (constructor) and `toolName` (in `start()`) **MUST** match regex `/^[a-z_0-9_]{2,}$/`:
-- Lowercase `a-z`, digits `0-9`, `_` **only**.
-- **Minimum 2 characters**.
-
-**Valid ✅**:
-- `myagent`
-- `chatbot`
-- `weather_agent`
-- `tool123`
-- `ws_client`
-
-**Invalid ❌ (throws `Error`)**:
-- `MyAgent` (uppercase)
-- `agent-v1` (hyphen)
-- `a` (too short)
-- `agent#tool` (`#` invalid)
-- `Agent_` (uppercase)
-
-**Why?** Safe for folders, tool names, filesystems (no specials/caps/spaces).
-
-## Quick Usage
-```javascript
-import AgentManager from '../lib/AgentManager.js';  // or '@j-o-r/hello-dave'
-
-const agent = new AgentManager({ name: 'myagent', secret: 'mysecret' });
-agent.setup({
-  prompt: 'You are a helpful coding assistant.',
-  api: 'xai',
-  options: { model: 'grok-4-fast-reasoning' },
-  toolsetMode: 'auto',
-  contextWindow: 128000
-});
-agent.addGenericToolcall('execute_bash_script');
-
-await agent.start();  // CLI mode
-// Or: await agent.directCall('Write a Bash script');  // One-shot
-// Or: await agent.start(8000);  // WS server on port 8000
-```
-
-## Constructor Options
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `name` | string | `'agent'` | **Agent ID (session folder, tool name). MUST match `/^[a-z_0-9_]{2,}$/` (lowercase a-z0-9_; ≥2 chars).** |
-| `secret` | string | `''` | WS auth (base64-encoded; optional, match server/client). |
-| `cachePath` | string | `'.cache/hello-dave'` | Session storage root. |
-
-## setup(setup) → `this` (chainable)
-Configures the agent. Must call before `start()`/`directCall()`.
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `prompt` | string | - | **Required**: System prompt. |
-| `api` | `'xai'|'gpt'|'claude'` | `'gpt'` | LLM provider (uses `lib/API/[provider]/text.js`). |
-| `options` | `XAIOptions`/`OAOptions`/etc. | `{}` | Provider-specific (model, temperature, tools, reasoning). |
-| `contextWindow` | number | `300000` | Token limit for `Prompt`. |
-| `toolsetMode` | `'auto'|'required'` | `null` | `'auto'`: Generic tools; `'required'`: Empty `ToolSet` (add manually). |
-| `debug` | boolean | `false` | Verbose logging. |
-
-Internals: Creates `Prompt`, `Session`, sets `Prompt.setAdaptor(API.text[api], toolset, options)`.
-
-## Key Methods
-| Method | Args | Returns | Description |
-|--------|------|---------|-------------|
-| `directCall(input)` | `string` | `Promise<string>` | One-shot query (via `prompt.call()`). |
-| `getPrompt()` | - | `Prompt` | Access internal `Prompt`. |
-| `getToolset()` | - | `ToolSet\|void` | Access tools. |
-| `environment()` | - | `Promise<EnvironmentInfo>` | System info (via `fafs.js/env()`). |
-| `addGenericToolcall(name)` | string (e.g., `'read_file'`) | - | Copy from `genericToolset.js` pool. Post-setup only. |
-| `start(servePort?, connectUrl?, cliIntro?, toolName?, toolDesc?)` | Mixed | `Promise<void>` | **Smart launcher**:<br>- `servePort` (num): WS **server** (**toolName** MUST match name regex or auto-gen).<br>- `connectUrl` (str, e.g. `'ws://127.0.0.1:8000/ws'`): WS **client** (toolName/desc for attachment).<br>- Neither: **CLI** mode.<br>- Both: Hybrid. |
-
-## Workflow Diagram
-```mermaid
-graph TD
-    A[New AgentManager name, secret] --> B[setup prompt, api, options, toolsetMode]
-    B --> C{start args?}
-    C -->|servePort| D[enableServer port, name, desc<br/>+ optional attach client]
-    C -->|connectUrl| E[attach client url, name, desc]
-    C -->|none| F[startCli intro]
-    D --> G[Session Loop: Prompt → API/Tools → Response]
-    E --> G
-    F --> G
-    G --> H[directCall or persist]
-```
-
-**Per-Endpoint Options**:
-- **CLI**: `start()` → `Cli` (interactive/piped). Options via `setup`.
-- **WS Server**: `start(port)` → `AgentServer` (localhost only). Exposes agent as tool (name/desc). `secret` required for clients. `prompt.on('reset')` → `server.resetAll()`.
-- **WS Client**: `start(undefined, url)` → `AgentClient`. Connects to remote server; agent callable as tool.
-- **Direct**: `directCall()` bypasses networking/CLI.
-
-## Examples
-
-### 1. Interactive CLI Agent
-```javascript
-const agent = new AgentManager({ name: 'chatbot' });
-agent.setup({
-  prompt: 'You are a friendly chatbot.',
-  api: 'xai',
-  toolsetMode: 'auto'
-});
-await agent.start('Chatbot ready!');  // Auto-generates intro
-```
-
-### 2. WS Server (Expose as Tool)
-```javascript
-agent.setup({ ... });
-await agent.start(8000, undefined, undefined, 'weathertool', 'Get real-time weather');
-```
-- Clients: `npx @j-o-r/hello-dave dave --connect ws://localhost:8000/ws --secret mysecret`
-
-### 3. Hybrid + Direct Call
-```javascript
-await agent.start(8001, 'ws://other:8000/ws');  // Server on 8001 + client to other
-const resp = await agent.directCall('Hybrid query');  // Uses attached tools too
-```
-
-### 4. Custom Tools + Generics
-```javascript
-agent.setup({ toolsetMode: 'required' });
-const ts = agent.getToolset();
-ts.add('customMath', 'Add numbers', {
-  type: 'object', properties: {a: {type: 'number'}, b: {type: 'number'}},
-  required: ['a', 'b']
-}, async ({a, b}) => a + b);
-agent.addGenericToolcall('javascript_interpreter');
-```
-
-## Advanced: Networking & Secrets
-- **Server-Client Chain**: Server A attaches to Server B → A callable from B (and vice versa if mutual).
-- **Cron/CLI Messaging**: Pipe to client: `echo 'query' | npx ... dave --connect ...`
-- **Reset**: `Prompt` emits `'reset'` → propagates to attached servers/clients.
-
-## Errors
-- No `setup()`: Throws.
-- **Invalid `name`/`toolName`: Regex `/^[a-z_0-9_]{2,}$/` fail → `Error`.**
-- No `toolset` on server: Throws.
-
-See source `lib/AgentManager.js` for full JSDoc/types. Cross-links:
-- [Prompt](./prompt-class.md)
-- [ToolSet](./toolset.md)
-- [Generic Tools](../lib/genericToolset.js)

package/docs.bak.1774780058/codeserver-pattern.md

@@ -1,191 +0,0 @@
-# CodeServer Pattern
-
-[![PM2](https://img.shields.io/badge/PM2-Managed-green.svg)](https://pm2.keymetrics.io/) [![WebSocket](https://img.shields.io/badge/WebSocket-Persistent-blue.svg)](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
-
-## Table of Contents
-
-- [Introduction & Motivation](#introduction--motivation)
-- [Architecture](#architecture)
-- [Prerequisites](#prerequisites)
-- [Step-by-Step Setup](#step-by-step-setup)
-- [Interaction via \`bin/dave.js\`](#interaction-via-bindavejs)
-- [Monitoring & Stopping with PM2](#monitoring--stopping-with-pm2)
-- [Customization](#customization)
-- [Benefits](#benefits)
-- [Troubleshooting](#troubleshooting)
-- [Integration with AgentManager](#integration-with-agentmanager)
-- [References](#references)
-
-## Introduction & Motivation
-
-The **CodeServer pattern** demonstrates a production-ready setup for running a **persistent, always-on agent server** managed by [PM2](https://pm2.keymetrics.io/). It launches:
-
-- **Main Server**: \`code_agent.js\` as a WebSocket server (code-focused agent with JavaScript tools).
-- **Sub-Agents (Clients)**: Specialized agents (\`todo_agent.js\`, \`readme_agent.js\`, \`npm_agent.js\`, \`docs_agent.js\`) that **attach as tools** to the main server via WebSocket.
-
-**Motivation**:
-- **Persistence**: Long-running sessions without restarts (state in \`.cache/hello-dave/[agent]/\`).
-- **Delegation**: Main agent delegates to specialists (e.g., "update docs" → \`docsDave\` tool).
-- **No Heartbeats**: PM2 handles restarts, monitoring—no custom pings.
-- **Scalability**: Easy to add sub-agents, deploy across machines.
-- **CLI-Friendly**: Interact via \`bin/dave.js --connect\`.
-
-Ideal for dev workflows: code execution, docs mgmt, npm inspection, todos—all in one persistent hub.
-
-See live example: [examples/CodeServer](../examples/CodeServer)
-
-## Architecture
-
-```mermaid
-graph TB
-    PM2[PM2 Process Manager] --> Main[Main: code_agent.js<br/>--serve PORT --secret SECRET<br/>WS Server on /ws]
-    PM2 --> Todo[todo_agent.js<br/>--connect ws://localhost:PORT/ws<br/>tool: todo_agent]
-    PM2 --> Readme[readme_agent.js<br/>--connect ...<br/>tool: readme_agent]
-    PM2 --> NPM[npm_agent.js<br/>--connect ...<br/>tool: npm_module_inspector]
-    PM2 --> Docs[docs_agent.js<br/>--connect ...<br/>tool: agent_docs]
-
-    User[bin/dave.js --connect] -.-> Main
-    Main -->|Delegates via tools| Todo & Readme & NPM & Docs
-    Todo -.->|File ops| ProjectFiles[(TODO.md, etc.)]
-    Docs -.->|Docs mgmt| DocsFolder[./docs/*.md]
-```
-
-**Key Flows**:
-1. PM2 spawns all processes (named \`FOLDER_agent_PORT\`).
-2. Clients connect to main server → auto-register as **tools** (e.g., \`todo_agent\`, \`readme_agent\`).
-3. User queries main server → delegates (e.g., \`call todo_agent {add: "new task"}\`).
-4. Sessions persist independently per agent.
-
-## Prerequisites
-
-| Requirement | Install Command | Notes |
-|-------------|-----------------|-------|
-| **Node.js** | `node --version` (≥18) | ESM support required. |
-| **PM2** | `npm i -g pm2` | Process manager. Startup: `pm2 startup`. |
-| **Project** | `git clone <repo> && cd hello-dave` | Examples in \`./examples/\`. |
-
-Verify: `pm2 --version` & `node -e "import('@j-o-r/hello-dave')"`
-
-## Step-by-Step Setup
-
-1. **Navigate to project**:
-   ```bash
-   cd /path/to/hello-dave
-   ```
-
-2. **Launch CodeServer** (pick PORT 1024-65535, SECRET ≥3 chars):
-   ```bash
-   ./examples/CodeServer 8080 mysecret123
-   ```
-   Output:
-   ```
-   Starting CodeServer on port 8080 in folder 'hello-dave' ... with SECRET 'mysecret123'
-   CodeServer processes spawned with prefix 'hello-dave_' and suffix _8080.
-   dave --connect ws://127.0.0.1:8080/ws --secret 'mysecret123'
-   ```
-
-3. **Verify PM2**:
-   ```bash
-   pm2 list | grep 8080
-   ```
-   | Name                  | Status | CPU | Memory |
-   |-----------------------|--------|-----|--------|
-   | hello-dave_code_agent_8080 | online | ... | ... |
-   | hello-dave_todo_agent_8080 | online | ... | ... |
-   | ... (4 total)         | ...   | ... | ... |
-
-## Interaction via \`bin/dave.js\`
-
-**Interactive**:
-```bash
-./bin/dave.js --connect 'ws://localhost:8080/ws' --secret 'mysecret123'
-```
-- Chat with **code_agent** (main agent).
-- Delegates automatically: "Manage todos", "Inspect @j-o-r/cli", "Update docs/codeserver-pattern.md".
-
-**Piped (one-shot)**:
-```bash
-echo "List pending todos" | ./bin/dave.js --connect 'ws://localhost:8080/ws' --secret 'mysecret123'
-echo "user_reset" | ./bin/dave.js --connect ...  # Reset session
-```
-
-**Delegation Examples**:
-- \`code_agent\`: "Use todo_agent to add 'Review PRs'"
-- \`code_agent\`: "Call agent_docs to create nodejs-guide.md"
-
-## Monitoring & Stopping with PM2
-
-**Monitor**:
-- `pm2 list` / `pm2 monit` (dashboard)
-- `pm2 logs hello-dave_code_agent_8080` (agent logs)
-- `pm2 logs *8080 --lines 50`
-
-**Stop**:
-```bash
-pm2 stop hello-dave_*_8080  # All related
-# Or delete:
-pm2 delete hello-dave_code_agent_8080 hello-dave_todo_agent_8080 ...
-```
-
-**Startup** (auto-restart on boot): `pm2 save && pm2 startup`
-
-## Customization
-
-### Adding Sub-Agents
-Edit [examples/CodeServer](../examples/CodeServer):
-```bash
-# Add new agent
-pm2 start "${SCRIPT_DIR}/newAgent.js" --name "${FOLDER}_new_agent_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-```
-- Create \`newAgent.js\` like [examples/todo_agent.js](../examples/todo_agent.js): Set \`tool_call_name\`, prompt.
-
-### Changing Tools
-- Main server: Edit \`code_agent.js\`: \`--tools javascript,bash,ssh\`
-- Sub-agents: \`agent.addGenericToolcall('read_file')\` etc. See [toolset.md](../toolset.md).
-
-### Prompts/Models
-- Per-agent: Edit JS files (e.g., \`options.model = 'grok-4-1-fast-reasoning'\`).
-
-## Benefits
-
-| Feature | Advantage |
-|---------|-----------|
-| **Persistent Sessions** | State in \`.cache/hello-dave/[name]/sessions/\`—no re-explaining. |
-| **Delegation** | Main agent uses sub-agents as tools (parallel, specialized). |
-| **No Heartbeat** | PM2 restarts on crash; no custom logic. |
-| **Resource Efficient** | Shared context; subs only active on call. |
-| **Portable** | Script auto-prefixes PM2 names by folder/port. |
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| **Port in use** | Change PORT; `lsof -i :8080` & `kill`. |
-| **Secret mismatch** | Ensure exact match (no extra spaces). |
-| **PM2 not found** | `npm i -g pm2`. |
-| **Connection refused** | Wait 5s for server startup; check `pm2 logs`. |
-| **No delegation** | Verify client tool names in JS (e.g., \`todo_agent\`). |
-| **High memory** | `pm2 del *` or tweak \`contextWindow\`. |
-
-Logs: `.cache/hello-dave/[agent]/sessions/*.ndjson` (use \`bin/dave.js --inspect log.ndjson\`).
-
-## Integration with AgentManager
-
-Built on [AgentManager](../docs/agent-manager.md):
-
-- **Server**: `agent.start(PORT)` → WS server exposing \`code_agent\`.
-- **Clients**: `agent.start(undefined, 'ws://...', undefined, 'todo_agent', 'desc')` → Attaches as tool.
-
-**Tools**: Generic from [toolset.md](../docs/toolset.md) (e.g., \`execute_bash_script\`, \`javascript_interpreter\`).
-
-Cross-links:
-- [Prompt Class](../docs/prompt-class.md)
-- [Generic Tools](../lib/genericToolset.js)
-
-## References
-
-- [PM2 Docs](https://pm2.keymetrics.io/docs/usage/quick-start/)
-- Examples: [CodeServer](../examples/CodeServer), [code_agent.js](../examples/code_agent.js), [todo_agent.js](../examples/todo_agent.js), etc.
-- Sessions: \`bin/dave.js --list\`
-
-**Updated**: March 24, 2026