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

package/docs/agent-dave-websocket-protocol.md

@@ -1,180 +0,0 @@
-# Agent Dave WebSocket Protocol
-
-**Version**: 0.0.8 (as of April 2026)  
-**Repository**: https://codeberg.org/duin/hello-dave  
-**Core Files**:
-- `lib/AgentServer.js` — Central hub, registers agents as dynamic tools, handles user interactions and sessions.
-- `lib/AgentClient.js` — Agent-side wrapper (Prompt + ToolSet), queue-based message processor, auto-reconnect, epoch-based reset handling.
-- `lib/wsIO.js` — One-shot WS client for CLI tools (`dave --connect`, `wsio()` helper).
-
-## Overview
-
-The protocol enables **multi-agent collaboration** over WebSocket. 
-
-- A central **AgentServer** listens on `ws://127.0.0.1:<port>/ws`.
-- **AgentClient** instances connect, introduce themselves, and get registered as **dynamic tools** in the server's `ToolSet`.
-- The server exposes these agents to the main Prompt, allowing the LLM to call them like any other tool (`agent_query` / `agent_response`).
-- **User/CLI interaction** uses `user_*` actions (via `wsIO.js` or `dave` CLI).
-- All messages are **JSON** objects with an `action` field validated against a fixed list.
-- **Authentication**: `?wssrc_id=<secret>` query param (plain in AgentServer, base64 in wsIO.js).
-- **Reset handling**: Broadcast `reset`, clients use an `#epoch` counter to invalidate in-flight work.
-- **Response matching**: Uses `id` (timestamp-based) + pending map on server.
-
-This design turns specialized agents (code, todo, memory, readme, etc.) into callable tools while supporting direct CLI, interactive REPL, and one-shot queries.
-
-## Message Format
-
-Every message is a JSON object:
-
-```json
-{
-  "action": "one_of_the_actions_below",
-  "content": "string or object (varies)",
-  "id": "unique_timestamp_string_or_number",
-  "name"?: "agent_name_on_introduction"
-}
-```
-
-### Supported Actions (ACTIONS array in AgentServer.js)
-
-**Agent ↔ Server (Tool Calls)**
-- `agent_introduction` — Agent registers itself (sends `name` + `description`).
-- `agent_query` — Server calls an agent tool with natural language `content` (query).
-- `agent_response` — Agent returns result.
-- `agent_error` — Agent reports failure.
-
-**User/CLI ↔ Server**
-- `user_introduction` — CLI connects (sent by wsIO.js).
-- `user_request` — User query to main prompt.
-- `server_response` — Final answer from main prompt.
-- `server_error` — Error from main prompt.
-- `user_reset` — Reset current session.
-- `user_sessionlist` — Request list of saved sessions.
-- `user_loadsession` — Load a previous session.
-- `user_info` — Get server/prompt/session info.
-
-**Server → Clients (broadcasts/responses)**
-- `reset` — Broadcast to all agents on reset.
-- `server_reset`, `server_sessionlist`, `server_sessionloaded`, `server_info` — Responses to user actions.
-
-Unknown actions cause immediate client disconnection.
-
-## Key Interactions & Sequence Diagrams
-
-### 1. Agent Registration & Tool Call
-
-```mermaid
-sequenceDiagram
-    participant AgentClient
-    participant AgentServer
-    participant Prompt/ToolSet
-
-    AgentClient->>AgentServer: WS connect + ?wssrc_id=secret
-    AgentClient->>AgentServer: {action: "agent_introduction", name: "code", content: "Code execution agent..."}
-    AgentServer->>ToolSet: add("code", description, schema, handler)
-    Note over ToolSet,AgentServer: Tool now available to LLM
-
-    Prompt->>ToolSet: LLM decides to call "code" with query
-    ToolSet->>AgentServer: handler(query) → Promise
-    AgentServer->>AgentClient: {action: "agent_query", id: "1745...", content: "Write a bash script..."}
-    AgentClient->>AgentClient: #queue.push(), #processOne()
-    AgentClient->>Prompt: prompt.call(query)
-    AgentClient->>AgentServer: {action: "agent_response", id: "1745...", content: "```bash ...```"}
-    AgentServer->>Prompt: resolve(promise)
-    Prompt->>LLM: Continue with tool result
-```
-
-### 2. User One-Shot Query (via wsIO.js or dave --connect)
-
-```mermaid
-sequenceDiagram
-    participant CLI (wsIO)
-    participant AgentServer
-    participant Prompt
-
-    CLI->>AgentServer: WS connect + wssrc_id
-    CLI->>AgentServer: {action: "user_introduction", id: X}
-    CLI->>AgentServer: {action: "user_request", id: Y, content: "Hello Dave"}
-    AgentServer->>Prompt: prompt.call("Hello Dave")
-    Prompt->>LLM: Full reasoning + tool calls (may call registered agents)
-    Prompt-->>AgentServer: Final content
-    AgentServer->>CLI: {action: "server_response", id: Y, content: "..."}
-    CLI->>CLI: resolve promise, close WS
-```
-
-### 3. Reset Handling
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant AgentServer
-    participant AgentClient
-
-    User->>AgentServer: {action: "user_reset"}
-    AgentServer->>Prompt: prompt.reset()
-    AgentServer-->>All Agents: broadcast {action: "reset"}
-    AgentClient->>AgentClient: #epoch++, #queue=[], prompt.reset()
-```
-
-## Implementation Details
-
-- **Server-side pending responses**: `pendingResponses` Map keyed by `${conn.id}:${msg.id}` with timeout via `setInterval` (30s intervals, max 20 → 10min).
-- **Client-side queue**: Strict sequential processing (`#processing` guard, 2s polling interval by default). Prevents race conditions in tool calls.
-- **Auto-reconnect**: AgentClient retries every 5s on close.
-- **Session Management**: Integrated with `Session.js` for `user_sessionlist` / `user_loadsession`.
-- **wsIO.js specifics**: Sends both `user_introduction` + action in one connection, matches response by `id`, then closes. Uses base64 secret.
-
-## Optimizations & Suggestions
-
-**Current Strengths**
-- Simple JSON, no complex framing.
-- Epoch prevents stale responses after reset.
-- Dynamic tool registration — agents can be added at runtime.
-
-**Potential Improvements**
-1. **Performance**:
-   - Replace polling interval in AgentClient with event-driven queue (e.g. `setImmediate` or microtask after each message).
-   - Use a proper request-response correlation library or WebSocket subprotocol.
-   - Add backpressure handling for high-volume tool calls.
-
-2. **Reliability**:
-   - Heartbeat/ping-pong to detect dead connections faster than timeout.
-   - Exponential backoff on reconnect.
-   - Persistent message IDs (UUID instead of timestamp).
-   - Schema validation for all incoming messages (e.g. Zod or JSON Schema).
-
-3. **Observability**:
-   - Add structured logging (instead of console.log).
-   - Metrics: active clients, avg response time, error rate.
-   - OpenTelemetry or Prometheus integration.
-
-4. **Security**:
-   - Current secret is weak (query param). Consider JWT or mTLS for production.
-   - Rate limiting per connection.
-   - Validate `content` size.
-
-5. **Extensibility**:
-   - Support binary messages for large data (e.g. images, files).
-   - Add `agent_stream` for streaming responses from agents.
-   - Formalize as a subprotocol (`Sec-WebSocket-Protocol: agent-dave-v1`).
-
-6. **Documentation**:
-   - Generate Mermaid diagrams automatically from code comments.
-   - Add protocol test suite in `scenarios/`.
-
-**Next Steps** (from TODO):
-- Complete sequence diagrams (expand the Mermaid examples above).
-- Identify specific performance bottlenecks via profiling.
-- Create formal spec with error codes and versioning.
-
-## References
-
-- `lib/AgentServer.js`
-- `lib/AgentClient.js`
-- `lib/wsIO.js`
-- `agents/spawn_agent.js` (uses this protocol for hybrid/server/client modes)
-- `docs/multi-agent-clusters.md`
-- `docs/prompt/spawn_agent.md`
-
-*Last updated: April 20, 2026*  
-*This document was generated as part of the TODO task "Document and review the 'agent dave websocket protocol'."*

package/docs/agent-manager.md

@@ -1,244 +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();  // Interactive CLI mode
-// Or: await agent.directCall('Write a Bash script');  // One-shot (pair with readIn for piped CLI)
-// 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()\`). **Ideal for piped CLI scripts & cron jobs.** |
-| \`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&lt;void&gt;\` | **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: **Interactive 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**:
-- **Interactive CLI**: \`start()\` → chat loop until Ctrl+C.
-- **One-Shot Piped CLI**: Custom script w/ \`readIn()\` + \`directCall()\` (stdin detection; exits after 1 response). No loop.
-- **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!');  // Interactive chat loop
-\`\`\`
-
-### 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');
-\`\`\`
-
-### 5. CLI One-Shot Piped Usage (Scripts/Cron)
-Uses \`@j-o-r/sh\` (\`readIn()\`, \`parseArgs()\`) + \`AgentManager.directCall()\` for fast, single-turn queries from stdin. **Detects piped input vs interactive** (empty stdin → help). Ideal for bash pipelines, cron jobs, automation.
-
-**Boilerplate Snippet** (see \`agents/grok_agent.js\`, \`agents/docs_agent.js\` etc.):
-\`\`\`javascript
-#!/usr/bin/env node
-import { AgentManager } from '@j-o-r/hello-dave';
-import { parseArgs, readIn } from '@j-o-r/sh';
-
-const name = 'grok_agent';  // Matches naming rules
-const api = 'xai';
-const secret = process.env.SECRET || '';
-
-const input = await readIn();
-const args = parseArgs();
-if (args.help || !input?.trim()) {
-  console.log(\`
-Usage: echo "query" | \${name}.js [--model grok-4] [--temperature 0.7]
-
-Options:
---model [str]          e.g., 'grok-4', 'grok-beta'
---temperature [float]  0.0 - 2.0
---tokens [int]         Max output tokens
---top_p [float]
---context [int]        Context window (default: 1.9M)
-  \`);
-  process.exit(0);
-}
-
-const options = {
-  tools: [{type: 'web_search'}, {type: 'x_search'}],
-  model: args.model || 'grok-4.20-multi-agent-0309',
-  temperature: args.temperature ? parseFloat(args.temperature) : undefined,
-  max_output_tokens: args.tokens ? parseInt(args.tokens) : undefined,
-  top_p: args.top_p ? parseFloat(args.top_p) : undefined,
-  reasoning: { effort: 'medium', summary: 'auto' }
-};
-
-const agent = new AgentManager({ name, secret });
-agent.setup({
-  prompt: 'Respond briefly and directly. Reason step-by-step first.',
-  api,
-  options,
-  toolsetMode: 'auto',
-  contextWindow: args.context ? parseInt(args.context) : 1900000
-});
-
-const res = await agent.directCall(input);
-console.log(res);
-\`\`\`
-
-**Bash Examples**:
-\`\`\`bash
-# Quick query
-echo "Explain async/await" | agents/grok_agent.js --model grok-4
-
-# Custom options
-echo "Daily summary" | agents/grok_agent.js --model grok-4 --temperature 0.1 --tokens 500
-
-# Cron job (append to log)
-0 8 * * 1 echo "Weekly report: sales data" | /path/to/grok_agent.js >> reports.log
-
-# Pipe chain
-cat data.txt | agents/docs_agent.js --model grok-4 | jq .
-\`\`\`
-
-**Interactive vs Piped**:
-| Mode | Invocation | Behavior |
-|------|------------|----------|
-| **Interactive** | \`agent.start()\` | Chat loop (multi-turn, until Ctrl+C). |
-| **Piped** | \`readIn() + directCall()\` | Single response, fast exit. Stdin empty → help. |
-
-**Suitability**: Cron/CLI automation (lightweight, no server). Complements WS modes.
-
-**Cross-Ref**: [README.md#cli-one-shot-with-example-agents](../README.md#cli-one-shot-with-example-agents) (\`agents/*.js\` ready-to-run).
-
-## 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 one-shot scripts (above) or WS clients: \`echo 'query' | npx @j-o-r/hello-dave 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/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: [agents/CodeServer](../agents/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 \`./agents/\`. |
-
-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
-   ./agents/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 [agents/CodeServer](../agents/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 [agents/todo_agent.js](../agents/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](../agents/CodeServer), [code_agent.js](../agents/code_agent.js), [todo_agent.js](../agents/todo_agent.js), etc.
-- Sessions: \`bin/dave.js --list\`
-
-**Updated**: March 24, 2026