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

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

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

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

@@ -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: [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

package/docs.bak.1774780058/path-resolution-best-practices.md

@@ -0,0 +1,104 @@
+# Path Resolution Best Practices for Generic Tools
+
+## Overview
+In `lib/genericToolset.js` and related tools (e.g., `syntax_check`, `write_file`), **path resolution** distinguishes between:
+- **Module-relative paths** (utils/scripts): Use `__dirname` for portability.
+- **User-provided file paths**: Resolve to `process.cwd()` (CWD sandbox) + strict validation.
+
+This ensures **sandboxing** (no escapes), **portability** (works from any CWD/PM2), and **security**. All tools enforce: no `/`, `..`, `\\\\`; `resolvedPath.startsWith(process.cwd())`.
+
+**ESM Setup** (genericToolset.js):
+```javascript
+const __dirname = path.dirname(fileURLToPath(import.meta.url));  // Polyfill for ESM
+```
+
+## __dirname vs process.cwd(): When to Use What
+
+| Context | Resolution | Example Code | Rationale |
+|---------|------------|--------------|-----------|
+| **Utils/Scripts** (e.g., syntax_check.sh, search_sessions.sh) | `__dirname` (module-rel) | `path.resolve(__dirname, '..', 'utils', 'syntax_check.sh')` | Portable: Locates utils/ from `lib/` regardless of CWD. Works in servers/clients. |
+| **User Files** (read/write/syntax/memory) | `process.cwd()` | `path.resolve(process.cwd(), params.file)` | Sandbox: Pins to project CWD (`~/devpri/js/hello-dave`). Prevents jailbreaks. |
+| **Cache/Memory** | `path.join(process.cwd(), '.cache/...')` | `.cache/hello-dave/memory.ndjson` | Per-project persistence. |
+| **Shebangs/Chmod** | Absolute (resolved) | `SH`chmod +x ${[resolvedPath]}` | Post-write on validated path. |
+
+**Universal Validation** (in read_file, write_file, syntax_check):
+```javascript
+const file = params.file?.trim();
+if (file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
+  throw new Error('Path must be relative within CWD only (no `/`, `..`, or `\\\\`).');
+}
+const resolvedPath = path.resolve(process.cwd(), file);
+if (!resolvedPath.startsWith(process.cwd())) {
+  throw new Error(`Path '${file}' escapes CWD scope.`);
+}
+```
+
+## syntax_check.sh Path Fix (User-Reported)
+
+**Issue** (Early Versions):
+- Relative paths passed to SH`` → Failed if CWD != lib/.
+- E.g., `SH`syntax_check.sh "rel/file.js"`` → "No such file" in sub-processes (PM2/CodeServer).
+
+**Fix** (Implemented):
+1. **Absolute Script Path**: `path.resolve(__dirname, '..', 'utils', 'syntax_check.sh')`.
+2. **Absolute File Arg**: `${syntaxChecker} "${resolvedPath}"` (resolvedPath = CWD-abs).
+3. **Script Handles Absolutes**: `FILE="$1"`; `head -n1 "$FILE"` works anywhere.
+
+**Test from Any CWD**:
+```bash
+cd /tmp
+/full/path/to/hello-dave/utils/syntax_check.sh /full/path/to/hello-dave/test.js  # ✅ JS OK
+# Or via tool: agent.directCall("syntax_check('test.js')")  # Resolves internally
+```
+
+**SH Best Practice**: Use array args `${[resolvedPath]}` → Auto-quotes/escapes paths with spaces.
+
+## Best Practices & Pitfalls
+
+### ✅ Do
+1. **Utils**: Always `__dirname, '..', 'utils', 'script.sh'` → Portable across deployments.
+2. **Files**: `process.cwd()` + validation → Sandboxed writes/reads.
+3. **SH Calls**: `SH`${script} ${[path]}`.run()` → Safe quoting via @j-o-r/sh.
+4. **Join vs Resolve**: `path.join(process.cwd(), '.cache')` for dirs; `resolve` for files.
+5. **ESM __dirname**: Polyfill with `fileURLToPath(import.meta.url)`.
+
+### ❌ Avoid
+1. `path.resolve(file)` → Assumes CWD; skips validation.
+2. `__dirname` for user files → Escapes to lib/ (security hole).
+3. Relative SH args → Breaks in non-lib CWD (e.g., WS clients).
+4. `process.chdir()` → Mutates global; use per-tool cwd.
+
+### Real-World Examples (from genericToolset.js)
+- **history_search**:
+  ```js
+  const history_search = path.resolve(__dirname, '..', 'utils', 'search_sessions.sh');
+  SH`${history_search} "${escapedQuery}"`.run();
+  ```
+- **syntax_check**:
+  ```js
+  const syntaxChecker = path.resolve(__dirname, '..', 'utils', 'syntax_check.sh');
+  return await SH`${syntaxChecker} "${resolvedPath}"`.run();
+  ```
+- **write_file** (AUTO-VALIDATE):
+  ```js
+  const syntaxChecker = path.resolve(__dirname, '..', 'utils', 'syntax_check.sh');
+  await SH`${syntaxChecker} ${[resolvedPath]}`.run();  // Throws on fail
+  ```
+
+## Troubleshooting
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| "No such file: utils/script.sh" | Wrong CWD | Use `__dirname` for utils. |
+| "Path escapes CWD" | `..` in input | Input validation blocks. |
+| SH arg unescaped | Spaces/specials | Array `${[path]}` auto-handles. |
+| ESM no __dirname | Node <20 | Polyfill shown above. |
+
+**Pro Tip**: For custom tools, copy pattern: `__dirname` (utils), `process.cwd()` (files).
+
+## Cross-Links
+- [ToolSet](../toolset.md#generic-tools)
+- [Syntax Validation](../tools-syntax-validation.md)
+- [genericToolset.js](../lib/genericToolset.js) (grep "path.resolve")
+- Utils: [syntax_check.sh](../utils/syntax_check.sh)
+
+**Updated**: March 27, 2026 (syntax_check.sh path fix documented).

package/docs.bak.1774780058/project-overview.md

@@ -0,0 +1,67 @@
+# Hello-Dave Project Overview
+
+## Root Directory
+The root contains essential project configuration, documentation, and entry points:
+- **README.md**: Main project documentation and setup instructions.
+- **TODO.md**: Outstanding tasks and development notes.
+- **package.json**: NPM package metadata, dependencies, and scripts.
+- **LICENSE**: Project license (Apache 2.0).
+- **jsconfig.json** / **tsc.json**: TypeScript/JavaScript configuration for editor and compiler support.
+- **.gitignore** / **.npmignore**: Git and NPM ignore rules.
+- **workspace.js**: Development or workspace management script.
+- Directories: `bin/`, `docs/`, `examples/`, `lib/`, `scenarios/`, `types/`, `utils/`, `release/`, `node_modules/`, `.cache/` (for sessions).
+
+## bin/
+Executable CLI scripts (npm bin entries) for spawning and interacting with specialized \"Dave\" agents. These are user-facing tools for quick tasks:
+- `spawn_agent.js`: Generates and runs custom agent scripts.
+- `ask_agent.js`, `chat2Dave.js`: General interactive chat/query.
+- `code_agent.js`: Code-related agent.
+- `prompt_agent.js`, `docs_agent.js`: Prompt engineering and docs management.
+- `readme_agent.js`, `todo_agent.js`: Project maintenance (README/TODO).
+- `npm_agent.js`: NPM module inspection/publishing.
+- Others: `formatDave.js`, `clearDave.js`, `CodeServer`.
+
+## lib/
+Core library code (ESM modules) **named exports only** from `lib/index.js` (NO default export):
+- **index.js**: Main export barrel (`{ AgentManager, Prompt, ToolSet, ... }`).
+- **AgentManager.js**: Central orchestrator for agents—handles setup, sessions, tools, networking (WS server/client), and `start()` for CLI/server modes.
+- **Prompt.js**: Conversation manager (EventEmitter)—tracks messages, tools, truncation, token counting, provider adapters.
+- **ToolSet.js**: Defines/extends tools (JSON Schema + handlers) like bash execution, web search, JS interpreter.
+- **AgentServer.js**, **AgentClient.js**: WebSocket server/client for agent networking.
+- **Session.js**: Persistent chat history/logs (NDJSON in `.cache/`).
+- **Cli.js**: CLI input/output handling.
+- **genericToolset.js**: Pre-configured toolset with common tools.
+- **fafs.js**, **promptHelpers.js**: Utilities (env, file access, prompt ops).
+- **API/**: Provider-specific wrappers (subdirs):
+  - `anthropic.com/`: Claude API.
+  - `brave.com/`: Search API.
+  - `openai.com/`: GPT API.
+  - `x.ai/`: Grok/xAI API (responses, files, collections).
+
+## Agent Workflow
+An **Agent** (via `AgentManager`) is configured with:
+1. **System prompt** (via `Prompt.js`): Defines personality/task.
+2. **API provider** (from `lib/API/`): xAI/Grok, OpenAI/GPT, Anthropic/Claude.
+3. **ToolSet** (`ToolSet.js`): Custom/local functions (e.g., `execute_bash_script`, `web_search`); extensible.
+4. **Session**: Conversation history.
+
+Modes: Standalone CLI, one-shot query, WS **server** (expose as tool), **client** (attach to server), hybrid. `bin/spawn_agent.js` generates custom agents leveraging this.
+
+## docs/
+Project documentation (Markdown) ✅ **Complete** (reviewed Mar 24, 2026):
+- `project-overview.md`: This file.
+- `prompt-class.md`: Deep dive on `Prompt.js`.
+- `toolset.md`: `ToolSet.js` details + 9 generics.
+- `agent-manager.md`: **AgentManager** workflows, options, Mermaid diagrams.
+- `xai-responses.md`: xAI Responses API integration/examples.
+- `xai-collections.md`: xAI Collections (raw; Later priority).
+
+## Other Directories
+- **examples/**: Usage demos (e.g., `daisy_agent.js` music agent).
+- **scenarios/**: Tests/demos (e.g., `grok_agent.js`, `wsAgent.js`).
+- **types/**: TypeScript `.d.ts` files.
+- **utils/**: Miscellaneous utilities.
+- **release/**: NPM pack artifacts.
+
+## Summary
+`hello-dave` (@j-o-r/hello-dave NPM pkg) is a lightweight ESM Node.js framework for **tool-using AI agents** with unified LLM access (Grok/Claude/GPT), WS networking, and CLI tools. **Import via named exports: `import { AgentManager } from '@j-o-r/hello-dave';`**. Focus: Rapid prototyping of domain agents (code, docs, music) via `AgentManager` + `Prompt` + `ToolSet` + APIs. Sessions in `.cache/`. Node >=20.