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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## Changelog
 
+### 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.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/.

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/docs/agent-manager.md

@@ -0,0 +1,244 @@
+# 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/bin-dave.md

@@ -0,0 +1,62 @@
+# Dave CLI Usage
+
+## Introduction
+
+The Dave CLI tool is the entry point for interacting with the Hello Dave project. It is located at `bin/dave.js` and can be run globally or via npx.
+
+## Installation
+
+### Global Installation
+
+To install globally and use the `dave` command:
+
+```bash
+npm install -g @j-o-r/hello-dave
+```
+
+### Local Usage with npx
+
+Run without installation:
+
+```bash
+npx @j-o-r/hello-dave [flags]
+```
+
+## Available Flags
+
+The CLI supports various flags for configuration and launching services. Common flags include:
+
+- `--help`: Display help information.
+- `--version`: Show the current version of the Dave CLI.
+- `--code [port] [--secret secret]`: Launch a portable CodeServer instance. Optionally specify a port (defaults to 8080 if omitted). Use `--secret` to set an access password for the server.
+
+For detailed information on the CodeServer pattern and integration, refer to [codeserver-pattern.md](codeserver-pattern.md).
+
+Other flags may be available depending on the version; run `dave --help` for the full list.
+
+## Examples
+
+### Basic Usage
+
+- Show help (global):
+  ```bash
+  dave --help
+  ```
+
+- Show version (npx):
+  ```bash
+  npx @j-o-r/hello-dave --version
+  ```
+
+### Launching CodeServer
+
+- Launch on default port (global):
+  ```bash
+  dave --code
+  ```
+
+- Launch on custom port with secret (npx):
+  ```bash
+  npx @j-o-r/hello-dave --code 3000 --secret mysecretpassword
+  ```
+

package/docs/codeserver-pattern.md

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