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

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

package/docs/generic-toolset.md

@@ -0,0 +1,326 @@
+# Generic Toolset Module (lib/genericToolset.js)
+
+## Overview
+
+The `genericToolset.js` module provides a pre-built collection of 11 utility tools designed for integration with the `ToolSet` class from the hello-dave library. These tools handle common operations like code execution, file I/O, system interactions, and memory management. They are exported as `toolsPool`, an object mapping tool names to `TSTool` objects (containing description, parameters schema, and execution method).
+
+This module is ideal for toolsets or utility libraries, enabling agents to perform real-world tasks without custom implementations. Tools follow OpenAI-style JSON Schema for parameters and support asynchronous execution.
+
+**Key Benefits**:
+- **Ready-to-Use**: Load into any `ToolSet` instance for immediate functionality.
+- **Secure & Sandboxed**: Tools operate in controlled environments (e.g., specific CWD, no escaping in Bash).
+- **Persistent State**: Memory tools allow offloading state from LLM context for efficiency.
+- **Documentation**: Each tool includes JSDoc annotations for IDE support and generated docs.
+
+To generate full JSDoc for this module (and the library):
+1. Install JSDoc: `npm install -g jsdoc`
+2. Run: `jsdoc lib/genericToolset.js -d docs/jsdoc/generic-toolset`
+3. View HTML docs in `docs/jsdoc/generic-toolset/index.html`.
+
+See [ToolSet Documentation](../toolset.md) for integration details.
+
+## Exports
+
+- **`toolsPool`**: `{ [name: string]: TSTool }` – Object with 11 pre-defined tools.
+  - `TSTool`: `{ description: string, parameters: TSSchema, method: async (params: object) => any }`
+  - `TSSchema`: JSON Schema object (e.g., `{ type: "object", properties: {...}, required: [...] }`).
+
+No default export; use named import: `import { toolsPool } from "@j-o-r/hello-dave/lib/genericToolset.js";`
+
+## Usage Examples
+
+### Basic Import and Population of ToolSet
+```javascript
+import { ToolSet } from "@j-o-r/hello-dave";
+import { toolsPool } from "@j-o-r/hello-dave/lib/genericToolset.js";
+
+const toolset = new ToolSet("auto"); // Or "required" for empty start
+
+// Add all generic tools
+Object.entries(toolsPool).forEach(([name, tool]) => {
+  toolset.add(name, tool.description, tool.parameters, tool.method);
+});
+
+// Or selectively
+toolset.add("memory_recall", toolsPool.memory_recall.description, toolsPool.memory_recall.parameters, toolsPool.memory_recall.method);
+
+// List available tools
+console.log(toolset.list());
+```
+
+### Integration with AgentManager
+```javascript
+import { AgentManager } from "@j-o-r/hello-dave";
+
+const agent = new AgentManager("my-agent");
+agent.setup({
+  toolsetMode: "auto" // Automatically loads all tools from toolsPool
+});
+
+// Add specific tools post-setup
+agent.addGenericToolcall("execute_bash_script");
+agent.addGenericToolcall("memory_write");
+```
+
+### Example: Using Memory Tools in a Prompt Workflow
+```javascript
+import { Prompt } from "@j-o-r/hello-dave";
+import { toolsPool } from "@j-o-r/hello-dave/lib/genericToolset.js";
+
+const prompt = new Prompt("You are a task manager. Use memory tools to track progress.");
+const toolset = new ToolSet("required");
+toolset.add("memory_write", ...toolsPool.memory_write); // Spread for destructuring
+
+// In agent loop: prompt.addMessage("Start new task: Implement login.");
+await toolset.execute(prompt); // LLM may call tools based on prompt
+```
+
+## Key Tools
+
+Below is a list of the 11 tools in `toolsPool`, with descriptions, parameter schemas, and usage examples. For full JSDoc details, generate docs as noted above.
+
+### 1. `javascript_interpreter`
+**Description**: Execute ESM ES6 JavaScript in a Node.js environment. Captures `console.log` output. CWD: `~/devpri/js/hello-dave`.
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": { "type": "string", "description": "JavaScript code to execute" }
+  },
+  "required": ["code"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("javascript_interpreter", { code: "console.log(2 + 2);" });
+// Returns: { output: "4\n", error: null }
+```
+
+### 2. `get_user_env`
+**Description**: Retrieve user environment details (name, system info, location, IP).
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {},
+  "required": []
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("get_user_env", {});
+// Returns: { name: "User", system: "Ubuntu 25.10", city: "Example City", ... }
+```
+
+### 3. `execute_bash_script`
+**Description**: Run raw Bash scripts/commands verbatim (no escaping). Supports Ubuntu 25.10 environment.
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "bash_script": { "type": "string", "description": "Raw Bash script (literal text)" }
+  },
+  "required": ["bash_script"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("execute_bash_script", { bash_script: "ls -la" });
+// Returns: { stdout: "...", stderr: "", exitCode: 0 }
+```
+
+### 4. `send_email`
+**Description**: Send email using `msmtp` (to, subject, body).
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "to": { "type": "string" },
+    "subject": { "type": "string" },
+    "body": { "type": "string" }
+  },
+  "required": ["to", "subject", "body"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("send_email", { to: "user@example.com", subject: "Hello", body: "Test" });
+// Returns: { success: true }
+```
+
+### 5. `open_link`
+**Description**: Open URL or file using `xdg-open`.
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "url": { "type": "string", "description": "URL or file path" }
+  },
+  "required": ["url"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("open_link", { url: "https://example.com" });
+// Returns: { opened: true }
+```
+
+### 6. `execute_remote_script`
+**Description**: Execute Bash script on remote server via SSH (`ssh://user@host[:port]`).
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "remote": { "type": "string", "description": "SSH URL" },
+    "script": { "type": "string", "description": "Bash script" }
+  },
+  "required": ["remote", "script"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("execute_remote_script", { remote: "ssh://user@host", script: "whoami" });
+// Returns: { stdout: "user\n", ... }
+```
+
+### 7. `history_search`
+**Description**: Search chat history sessions using regex (e.g., in `.cache/[app]/[prompt]/sessions/*.ndjson`).
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "Regex query" }
+  },
+  "required": ["query"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("history_search", { query: package.json });
+// Returns: [{ session: "path", matches: [...] }, ...]
+```
+
+### 8. `read_file`
+**Description**: Read file content from CWD (relative path, no absolute/parent traversal).
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "path": { "type": "string", "description": "Relative file path" }
+  },
+  "required": ["path"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("read_file", { path: "example.txt" });
+// Returns: { content: "File text\n", encoding: "utf8" }
+```
+
+### 9. `write_file`
+**Description**: Write raw content to file in CWD (relative path). Returns bytes written.
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "path": { "type": "string" },
+    "content": { "type": "string" }
+  },
+  "required": ["path", "content"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("write_file", { path: "output.txt", content: "Hello World" });
+// Returns: { bytesWritten: 11 }
+```
+
+### 10. `memory_recall`
+**Description**: Recall latest values for keys from agent-specific memory (`.cache/[agent]/memory.ndjson`).
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of keys to recall"
+    }
+  },
+  "required": ["keys"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("memory_recall", { keys: ["current_task"] });
+// Returns: { current_task: "Implement login" } or {}
+```
+
+### 11. `memory_write`
+**Description**: Append/update key-value pairs in agent memory (overwrites same keys).
+
+**Parameters Schema**:
+```json
+{
+  "type": "object",
+  "properties": {
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "key": { "type": "string" },
+          "value": { "type": "string" }
+        },
+        "required": ["key", "value"]
+      }
+    }
+  },
+  "required": ["entries"]
+}
+```
+
+**Usage Example**:
+```javascript
+await toolset.call("memory_write", { entries: [{ key: "step", value: "1/5" }] });
+// Returns: { stored: [{ key: "step", value: "1/5" }] }
+```
+
+## Best Practices
+- **Security**: Tools like `execute_bash_script` and `write_file` are powerful; use in trusted environments.
+- **Error Handling**: Methods return `{ success: boolean, error?: string, data: any }` for robustness.
+- **Customization**: Extend `toolsPool` by adding your own tools before populating `ToolSet`.
+- **JSDoc Integration**: Annotations include `@param`, `@returns`, `@example` for full type safety in editors like VS Code.
+
+For syntax validation in tools (e.g., JS in `write_file`), see [Tools Syntax Validation](../tools-syntax-validation.md). For path handling, see [Path Resolution Best Practices](../path-resolution-best-practices.md).
+
+**Updated**: April 10, 2026