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

package/agents/spawn_agent.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+import fs from 'fs';  // Added for local fallback
+
+const name = 'spawn_agent';
+const api = 'xai';
+let secret = '';
+
+const args = parseArgs();
+
+let input;
+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;
+
+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']);
+}
+if (true) {
+        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):
+./${name}.js "Create a code agent" [--options]
+
+### 2. Interactive CLI (no positional arg):
+./${name}.js [--options]
+
+### 3. WS Server (no positional arg):
+./${name}.js --serve 8080 [--secret mysecret] [--options]
+
+### 4. WS Client (no positional arg):
+./${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+
+### 5. Hybrid (Server + Client, no positional arg):
+./${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+
+## PORTABILITY NOTES:
+- **Tools follow YOUR CWD** (e.g., cd /tmp/proj && ./spawn_agent.js → tools in /tmp/proj).
+- **Hybrid Modes**: PROJECT (agents/*.js exist): Auto-deploy/test. FRESH (empty agents/): Code + manual bash.
+- **Custom Tools**: natives=web_search, generics=read_file, custom={type:'git_diff',...}
+
+## OPTIONS:
+--model [grok-4-fast-reasoning|...] (default: grok-4-fast-reasoning)
+--temperature [float] (0.8)
+--tokens [number]
+--top_p [float]
+--context [number] (250k)
+
+## Examples:
+"Create coderev: desc=Git analyzer, natives=web_search, generics=read_file execute_bash_script, custom=options.tools.push({type:'git_diff',description:'...',parameters:{...}})"
+`);
+        process.exit();
+}
+
+if (help) {
+        printHelp();
+}
+
+const tool_call_name = 'spawn_agent';
+const tool_call_description = `Portable creator for CLI/WS agents + PM2 launchers. Tools use exec CWD (/tmp OK). PROJECT (agents/*.js >0): Full auto. FRESH: Manual code/bash.
+
+Test new agent: ./agents/NEW.js --help | 'describe' | --serve 8081 --secret abc
+
+Custom ex: natives=[{type:'mytool'}], generics=read_file
+
+Live prompt: https://codeberg.org/duin/hello-dave/raw/branch/main/docs/prompt/spawn_agent.md`.trim();
+
+const REPO_URL = 'https://codeberg.org/duin/hello-dave';
+
+
+async function fetchLivePrompt() {
+  // Priority 1: Remote
+    const promptUrl = `${REPO_URL}/raw/branch/main/docs/prompt/spawn_agent.md`;
+    const response = await fetch(promptUrl);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    return await response.text();
+}
+
+const agent = new AgentManager({ name, secret });
+
+const prompt = await fetchLivePrompt();
+
+agent.setup({
+  prompt,
+  api,
+  options,
+  toolsetMode,
+  contextWindow
+});
+
+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 Creator: PROJECT (agents/*.js exist): Auto. FRESH (empty): Manual code.
+
+Ex: "Create testagent: desc=Tester, natives=web_search"`.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/{examples → agents}/test_agent.js

@@ -55,19 +55,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Generate test for toolset.js" [--options]
+./agents/${name}.js "Generate test for toolset.js" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${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]
+./agents/${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]
+./agents/${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., 'test_agent'). Runs indefinitely until Ctrl+C.
@@ -108,7 +108,7 @@ const prompt = `You are TestAgent, the specialized testing agent for CodeServer
 - Tests must use: \`import { Test, assert, jsType } from '@j-o-r/sh';\`
 - Structure: shebang \`#!/usr/bin/env node\`, fluent Test API (\`const t = new Test(); t.add('desc', () => { assert... }); await t.run();\`), exit(1) on errors.
 - After write_file to scenarios/MODULE.test.js, ensure executable: \`chmod +x scenarios/MODULE.test.js\`
-- Leverage project utilities: test existing files (examples/*.js, toolset.js, agents, SH commands, etc.) using read_file, execute_bash_script (ls/cat), npm_module_inspector.
+- Leverage project utilities: test existing files (agents/*.js, toolset.js, agents, SH commands, etc.) using read_file, execute_bash_script (ls/cat), npm_module_inspector.
 
 **WHAT TO TEST** (discover dynamically):
 1. Project scripts: e.g., parseArgs, AgentManager flows, toolsets.

package/{examples → agents}/todo_agent.js

@@ -55,19 +55,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "List tasks" [--options]
+./agents/${name}.js "List tasks" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${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]
+./agents/${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]
+./agents/${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., 'todo_agent'). Runs indefinitely until Ctrl+C.

package/bin/codeDave

@@ -0,0 +1,58 @@
+#!/bin/bash
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  echo "Usage: $0 <PORT> [SECRET]  # PORT: 1024-65535, SECRET: optional (defaults to '123')"
+  exit 1
+fi
+
+PORT="$1"
+SECRET="${2:-123}"
+
+if [ -z "$SECRET" ] || [ ${#SECRET} -lt 3 ]; then
+  echo "Error: SECRET must be at least 3 characters: '$SECRET'"
+  exit 1
+fi
+
+if ! [[ "$PORT" =~ ^[0-9]+$ ]] || [ "$PORT" -lt 1024 ] || [ "$PORT" -gt 65535 ]; then
+  echo "Error: Invalid port number: $PORT. Must be between 1024 and 65535."
+  exit 1
+fi
+
+# Compute canonical paths relative to THIS script's real location (resolves symlinks for global npm installs)
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+PROJECT_DIR="$( cd -P "$( dirname "$SCRIPT_DIR" )" >/dev/null 2>&1 && pwd )"
+
+# FOLDER: basename of CURRENT WORKING DIRECTORY (pwd) for per-project PM2 prefixes (e.g., myproject_code_8080)
+# This allows multi-project usage without name conflicts; PROJECT_DIR remains package location for agents/
+FOLDER=$(basename "$(pwd)")
+
+echo "Starting codeDave on port ${PORT} in folder '${FOLDER}' (SCRIPT_DIR: ${SCRIPT_DIR}) with SECRET '${SECRET}'..."
+
+# Delete existing processes with folder_port suffix
+pm2 delete "${FOLDER}_code_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_todo_${PORT}"  2>/dev/null || true
+pm2 delete "${FOLDER}_readme_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_npm_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_docs_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_test_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_memory_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_spawn_${PORT}" 2>/dev/null || true
+
+# Spawn main Agent / server (absolute paths to scripts)
+pm2 start "${PROJECT_DIR}/agents/code_agent.js" --name "${FOLDER}_code_${PORT}" -- --serve "${PORT}" --tools javascript --secret "${SECRET}"
+# Attach clients
+pm2 start "${PROJECT_DIR}/agents/todo_agent.js"   --name "${FOLDER}_todo_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${PROJECT_DIR}/agents/readme_agent.js" --name "${FOLDER}_readme_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${PROJECT_DIR}/agents/npm_agent.js"    --name "${FOLDER}_npm_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${PROJECT_DIR}/agents/docs_agent.js"   --name "${FOLDER}_docs_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${PROJECT_DIR}/agents/test_agent.js"   --name "${FOLDER}_test_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${PROJECT_DIR}/agents/memory_agent.js" --name "${FOLDER}_memory_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${PROJECT_DIR}/agents/spawn_agent.js"  --name "${FOLDER}_spawn_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+
+echo "codeDave processes spawned with prefix '${FOLDER}_' and suffix _${PORT}. Check with: pm2 list | grep '${FOLDER}_${PORT}'"
+echo "dave --connect ws://127.0.0.1:${PORT}/ws --secret '$SECRET'"

package/bin/dave.js

@@ -1,9 +1,7 @@
 #!/usr/bin/env -S node
 import path from 'node:path';
 import cli from '@j-o-r/cli';
-import wsCli from '../lib/wsCli.js';
-import wsIO from '../lib/wsIO.js';
-import { AgentManager } from '@j-o-r/hello-dave';
+import { AgentManager, wsCli, wsIO } from '@j-o-r/hello-dave';
 import { SH, parseArgs, readIn, bashEscape } from '@j-o-r/sh';
 import { fileURLToPath } from 'node:url';
 
@@ -31,7 +29,7 @@ FLAGS:
   Remote:       bin/dave.js --ask --connect 'ws://localhost:8080' --secret '123'
   Piped local:  echo "predict the weather" | bin/dave.js --ask
   Piped remote: echo "predict the weather" | bin/dave.js --ask --connect 'ws://...' --secret '123'
---code [port] [--secret "..."] : Launch CodeServer PM2 cluster via examples/codeserver.sh
+--code [port] [--secret "..."] : Launch CodeServer PM2 cluster via agents/codeserver.sh
   Usage: bin/dave.js --code 8080 --secret 123
 `);
 	process.exit(exitCode)
@@ -193,4 +191,4 @@ ${name} (${options.model}).
 	const RES = await SH`${server} ${port} ${bashEscape(secret)}`.run();
 	console.log(RES);
 	process.exit(0);
-}
+}

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
+  ```
+