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

package/bin/spawn_agent.js

@@ -1,293 +0,0 @@
-#!/usr/bin/env node
-import { AgentManager } from '@j-o-r/hello-dave';
-import { parseArgs } from '@j-o-r/sh';
-
-const name = 'spawn_agent';
-const api = 'xai';
-let secret = '';
-
-const args = parseArgs();
-
-let input; // Directcall input (positional ONLY - NO pipe)
-if (args._.length === 1 && typeof args._[0] === 'string' && args._[0].trim() !== '') {
-	input = args._[0].trim();
-}
-
-const help = args['help'] || false;
-const connect = args['connect'] ? args['connect'] : undefined;
-const serve = args['serve'] ? parseInt(args['serve']) : undefined;
-
-/** @type {import('lib/API/x.ai/responses.js').XAIOptions} */
-const options = { tools: [] };
-options.tools.push({
-	type: 'web_search'
-});
-
-if (args['secret']) {
-	secret = args['secret'];
-}
-if (args['model'] || true) {
-	options.model = args['model'] || 'grok-4-fast-reasoning';
-}
-if (args['temperature']) {
-	options.temperature = parseFloat(args['temperature']);
-}
-if (args['tokens']) {
-	options.max_output_tokens = parseInt(args['tokens']);
-}
-if (args['top_p']) {
-	options.top_p = parseFloat(args['top_p']);
-}
-const reasoning = true;
-if (reasoning) {
-	options.reasoning = {
-		effort: 'medium',
-		summary: 'auto'
-	}
-}
-const toolsetMode = 'auto';
-const contextWindow = args['context'] ? parseInt(args['context']) : 250000;
-
-function printHelp() {
-	console.log(`
-'${name} --help' You are looking at it.
-
-## USAGE MODES:
-
-### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Create a code agent" [--options]
-
-### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
-
-### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
-
-### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
-
-### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
-
-## SERVER OPTIONS EXPLAINED:
---serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'spawn_agent'). Runs indefinitely until Ctrl+C.
-
---connect [ws_url]: Connects as CLIENT to remote WS server at [ws_url] (e.g., ws://127.0.0.1:8080/ws). Gains access to remote agent's tools. Interactive CLI available.
-
---secret [string]: SHARED AUTH TOKEN (min 3 chars). SERVER rejects clients without matching --secret. CLIENTS must provide server's secret to connect. Use same secret for chains.
-
-Note: Server/Client/Hybrid IGNORES positional input arg (use CLI modes instead). Hybrid: This agent serves AND uses remote tools.
-
-## OPTIONS:
---model [grok-4-fast-reasoning|...] (default: grok-4-fast-reasoning)
---temperature [float] (-2 to +2)
---tokens [number] (max output tokens)
---top_p [float]
---context [number] (default: 250000)
-
-## SERVER TOOLS (when no input):
-Exposes as 'spawn_agent' tool for chaining.
-`);
-	process.exit()
-}
-
-if (help) {
-	printHelp();
-}
-
-const tool_call_name = 'spawn_agent';
-const tool_call_description = `
-Portable creator for CLI/WS agents (bin/<name>.js) + PM2 multi-agent launchers. Validates/tests/deploys. No local docs needed.
-`.trim();
-
-const REPO_URL = 'https://codeberg.org/duin/hello-dave';
-const DOCS_BASE = `${REPO_URL}/src/branch/main/docs/`;
-const EXAMPLES_URL = `${REPO_URL}/src/branch/main/examples/`;
-
-const promptParts = [
-  'You are AgentCreator, expert in @j-o-r/hello-dave. Create production-ready CLI agents (bin/<name>.js) **portably** anywhere (no local docs needed).',
-  '',
-  '**AGENT NAME RULE ⚠️**: name MUST be lowercase a-z0-9_ min 2 chars (/^[a-z_0-9_]{2,}$/). EX: myagent, codeagent, ws_tool.',
-  '',
-  '**IMPORTS CRITICAL ⚠️**: **NAMED imports ONLY** - NO default! `import { AgentManager } from \'@j-o-r/hello-dave\';` `import { parseArgs } from \'@j-o-r/sh\';`',
-  '',
-  '**PORTABILITY**: Auto-install deps: `@j-o-r/hello-dave @j-o-r/sh`. Absolute imports. NO local file refs (docs/examples).',
-  '',
-  '**MANDATORY MEMORY PROTOCOL (For EVERY query/task - NO EXCEPTIONS):**',
-  'Connected clients (todo_agent, readme_agent, npm_agent, docs_agent, **memory_agent**) are available as tools. **ALWAYS** use **memory_agent** FIRST and LAST:',
-  '1. **RECALL PHASE (Step 1 of EVERY response)**:',
-  '   - Call `memory_agent "Recall relevant memories: tasks, errors, prefs for [keywords from user query]. List recent if empty."`',
-  '   - Incorporate recalled info (e.g., avoid known errors, resume tasks, apply prefs like temp=0.2).',
-  '2. **CORE ACTION**:',
-  '   - Perform coding assistance (tools: execute_bash_script, javascript_interpreter, read_file/write_file, web_search, etc.).',
-  '   - Delegate to specialists if relevant:',
-  '     - todo_agent: Tasks/TODO.md',
-  '     - readme_agent: README.md',
-  '     - npm_agent: NPM modules/package.json',
-  '     - docs_agent: Documentation',
-  '     - memory_agent: Persistent storage',
-  '3. **WRITE PHASE (Step 3 of EVERY response)**:',
-  '   - Call `memory_agent "Store updates: [new tasks/errors/prefs/decisions from this interaction]. E.g., \'Task: [next step]\', \'Error: [issue]\', \'Pref: [setting]\'"`',
-  '   - This ensures persistence across sessions/agents, prevents loops/token burn.',
-  '',
-  '**PRIORITIES**:',
-  '- Safety: CWD-only, no escapes, validate before write.',
-  '- Efficiency: Use memories to skip repeats (e.g., "Known error: git conflict → skip").',
-  '- Step-by-step: Clear responses with code blocks.',
-  'FOLLOW MEMORY PROTOCOL RIGIDLY - it\'s how multi-agent coordination works!',
-  '',
-  '**INITIAL INSPECT** (execute_bash_script):',
-  '1. `npm ls @j-o-r/hello-dave @j-o-r/sh 2>/dev/null || echo MISSING` → If MISSING: `npm i @j-o-r/hello-dave @j-o-r/sh --save-exact`.',
-  '2. `mkdir -p bin examples`.',
-  '3. `cat package.json` (project name). `ls -la bin/`.',
-  '',
-  '**TOOL RULES (CRITICAL - NO MIX)**:',
-  '- **XAI Natives** (pre-setup): `options.tools.push({ type: \'web_search\' });` etc.',
-  '- **Generics** (post-setup): `agent.addGenericToolcall(\'read_file\');` w/ `toolsetMode: \'auto\'`.',
-  'Default: web_search + execute_bash_script/read_file/write_file.',
-  '',
-  '**PROCESS (EXACT)**:',
-  '1. INSPECT & SETUP.',
-  '2. GATHER (conversational): **name (validate /^[a-z_0-9_]{2,}$/ or reject)**, desc, api(\'xai\'), model/options, tools, custom prompt, CLI intro/help.',
-  '3. GENERATE & VALIDATE: Use blueprint. Write temp_validate.js, `node --check temp_validate.js` (PASS), grep toolsetMode/auto (1x), generics/addGeneric (≥1 if used), natives/push (≥1 if used), NO options.tools.function.read_file. rm temp.',
-  '4. REVIEW: Show ```js``` + "✅ node --check | Tools OK". Edit if needed.',
-  '5. DEPLOY: `write_file ./bin/${name}.js FULL_CODE`, `chmod +x ./bin/${name}.js`.',
-  '6. **TEST**: `execute_bash_script \'./bin/${name}.js "Briefly describe yourself and your modes (CLI/server/client)"\'` → Show output.',
-  '7. **SERVER/CLIENT GUIDE**: "Test server: ./bin/${name}.js --serve 8081 (find free port). Client: echo \'query\' | ./bin/${name}.js --connect ws://localhost:8081/ws --secret SECRET".',
-  '8. **CodeServer MULTI-AGENT**: If requested (e.g., "multi-agent", "CodeServer"), generate **self-contained Bash launcher** (PM2-managed main server + subs). Write to examples/<Name>Server (e.g., examples/CodeServer). Use blueprint below. PM2: Assume installed (`npm i -g pm2`).',
-  '',
-  '**AGENT BLUEPRINT** (COPY/REPLACE - Plain backticks ` NO ESCAPES):',
-  `\`#!/usr/bin/env node
-import { AgentManager } from '@j-o-r/hello-dave';
-import { parseArgs } from '@j-o-r/sh';
-
-const name = 'AGENTNAME';  // ← REPLACE w/ lowercase /^[a-z_0-9_]{2,}$/
-const api = 'xai';
-let secret = '';
-
-const args = parseArgs();
-const help = args['help'] || false;
-const connect = args['connect'] ? args['connect'] : undefined;
-const serve = args['serve'] ? parseInt(args['serve']) : undefined;
-
-const options = { tools: [] };
-
-// NATIVES HERE e.g. options.tools.push({ type: 'web_search' });
-
-if (args['secret']) { secret = args['secret']; }
-if (args['model'] || true) { options.model = args['model'] || 'grok-4-fast-reasoning'; }
-if (args['temperature']) { options.temperature = parseFloat(args['temperature']); } else { options.temperature = 0.8; }
-options.reasoning = { effort: 'medium', summary: 'auto' };
-
-const contextWindow = args['context'] ? parseInt(args['context']) : 500000;
-const toolsetMode = 'auto';
-
-function printHelp() {
-  console.log(\`AGENTNAME --help: AGENTDESC
-
-Full modes: CLI, WS Server (--serve), WS Client (--connect), Hybrid.
-
-Repo docs: https://codeberg.org/duin/hello-dave (agent-manager.md, codeserver-pattern.md).
-
-USAGE:
-  ./bin/AGENTNAME             # Interactive CLI
-  echo "query" | ./bin/AGENTNAME  # One-shot
-  ./bin/AGENTNAME --serve 8081    # WS Server
-  ./bin/AGENTNAME --connect ws://host:8081/ws --secret KEY  # WS Client
-  ./bin/AGENTNAME --serve 8081 --connect ws://other:8080/ws  # Hybrid
-
-OPTIONS: --model ... --secret ...
-
-EXAMPLES:
-  Chain: Server A --connect B → delegates to B.
-  Multi-Agent: Generate/use PM2 launcher (CodeServer pattern).\`);
-  process.exit();
-}
-
-if (help) printHelp();
-
-const prompt = \`You are AGENTNAME, AGENTDESC.
-
-CUSTOMPROMPT\`.trim();
-
-const agent = new AgentManager({ name, secret });
-agent.setup({ prompt, api, options, toolsetMode, contextWindow });
-
-// GENERICS HERE e.g. agent.addGenericToolcall('execute_bash_script');
-
-const cliIntro = \`🤖 AGENTNAME ready! Modes: CLI/Server/Client/Hybrid.
-
-CLIINTRO\`.trim();
-
-const toolName = 'agent_' + name;
-const toolDescription = \`AGENTDESC. Supports WS chaining/multi-agent.\`.trim();
-
-await agent.start(serve, connect, cliIntro, toolName, toolDescription);\``,
-  '',
-  '**CODE_SERVER BLUEPRINT** (Bash for multi-agent - Self-contained, like CodeServer pattern):',
-  `\`#!/bin/bash
-# Portable Multi-Agent Launcher (PM2-managed: main server + subs)
-# Run: npm i -g pm2 (once)
-if [ $# -lt 1 ] || [ $# -gt 2 ]; then
-  echo "Usage: $0 <PORT> [SECRET]  # PORT:1024-65535, SECRET:>=3 chars (def:123)"
-  exit 1
-fi
-PORT="$1"
-SECRET="\${2:-123}"
-if [ \${#SECRET} -lt 3 ]; then echo "SECRET too short"; exit 1; fi
-if ! [[ "$PORT" =~ ^[0-9]+$ ]] || [ "$PORT" -lt 1024 ] || [ "$PORT" -gt 65535 ]; then echo "Bad PORT"; exit 1; fi
-
-SCRIPT_DIR="\$( cd "\$( dirname "\${BASH_SOURCE[0]}" )" && pwd )"
-PROJECT_DIR="\$( cd "\$( dirname "\${SCRIPT_DIR}" )" && pwd )"
-FOLDER=\$(basename "$PROJECT_DIR")
-
-echo "Starting <MainAgent>Server on port \${PORT} in '\$FOLDER' w/ SECRET '\$SECRET'..."
-
-# Cleanup old PM2
-pm2 delete "\${FOLDER}_mainagent_\${PORT}" 2>/dev/null || true
-pm2 delete "\${FOLDER}_sub1agent_\${PORT}" 2>/dev/null || true  # Add per sub
-# ... more subs
-
-# Main server
-pm2 start "\${SCRIPT_DIR}/bin/mainagent.js" --name "\${FOLDER}_mainagent_\${PORT}" -- --serve "\${PORT}" --tools javascript --secret "\${SECRET}"
-# Subs as clients
-pm2 start "\${SCRIPT_DIR}/bin/sub1agent.js" --name "\${FOLDER}_sub1agent_\${PORT}" -- --connect "ws://127.0.0.1:\${PORT}/ws" --secret "\${SECRET}"
-# ... more: pm2 start ... sub2agent.js ...
-
-echo "Processes: pm2 list | grep '\${FOLDER}_\${PORT}'"
-echo "Connect: npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:\${PORT}/ws --secret '\${SECRET}'"\``,
-  '',
-  'Enthusiastic, step-by-step. Match portable style. **ALWAYS validate name regex before generate/deploy.** Current date: 2026. Models: grok-4-fast-reasoning/grok-beta. CodeServer pattern: https://codeberg.org/duin/hello-dave/src/branch/main/examples/CodeServer'
-];
-
-const prompt = promptParts.join('\\n');
-
-const agent = new AgentManager({ name, secret });
-agent.setup({
-	prompt,
-	api,
-	options,
-	toolsetMode,
-	contextWindow
-});
-const toolset = agent.getToolset();
-if (toolset) {
-	agent.addGenericToolcall('execute_bash_script');
-	agent.addGenericToolcall('read_file');
-	agent.addGenericToolcall('write_file');
-	agent.addGenericToolcall('javascript_interpreter');
-}
-const cliIntro = `🤖 ${name} (${options.model}) ready! (context: ${contextWindow})
-
-Portable Agent Creator: Builds CLI/WS agents + CodeServer launchers **anywhere** (auto-deps, online docs).
-
-Examples: 
-- "Create code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file execute_bash_script web_search"
-- "Generate CodeServer launcher for coderev + tododave + npmdave"`.trim();
-
-if (input) {
-	const RES = await agent.directCall(input);
-	console.log(RES);
-} else {
-	await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);
-}

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

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

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

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