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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## Changelog
 
+### v0.0.8 (Released - April 15, 2026)
+- **lib/genericToolset.js Timeout Refinements**: Switched `execute_bash_script` to @j-o-r/sh `.options({timeout: ms}).run()` with heredoc delimiter for verbatim multi-line bash_script safety. Default 360s (resets on stdout/stderr output for true idle detection only), SIGTERM on expiry. `execute_remote_script` stdin pipe preserved. Tests: success, sleep timeout (3s<7s), exit1 error, interactive `read -p` no hang.
+- **TODO.md Cleanup**: Archived all completed tasks (timeout refinements, prior v0.0.7 carryovers) to `docs/todo-archive-v0.0.8.md`. Pending changelog task completed here. Clean post-release state.
+- **.npmignore & package-lock.json**: Minor updates for cleaner packaging.
+- **Release Prep**: `package.json` bumped to v0.0.8. `npm run release` ready (types + pack to `./release/`).
+
 ### v0.0.7 (Released - April 13, 2026)
 - **spawn_agent Enhancements**: Strict blueprint enforcement in `docs/prompt/spawn_agent.md` (mandatory tool sequence: INSPECT → VALIDATE → GATHER → GENERATE → AUTO-DEPLOY/TEST). Fixed one-shot hallucination/no-deploy via verbatim AGENT BLUEPRINT TEMPLATE, temp_agent.js validation (syntax/blueprint checks), PROJECT auto-deploy (write/mv/chmod/test/rm), FRESH manual code/bash. Robust fetchLivePrompt() (live MD full-load + fallbacks). CodeServer/PM2 awareness (LAUNCH_MODE detect, client connect hints). Tested 2026-04-13: /tmp FRESH, PROJECT diag_agent.js deploy+--help success.
 - **JSDoc Updates (lib/ modules)**: Comprehensive JSDoc added/fixed for AgentClient.js, AgentManager.js, AgentServer.js, Cli.js, Prompt.js, Session.js, ToolSet.js, fafs.js, genericToolset.js, wsCli.js, wsIO.js. Typedefs, @returns, @private tags. Note: Some parser warnings (HTML entities &lt; → &lt;, import() expr); HTML generated in docs/jsdoc/.

package/TODO.md

@@ -0,0 +1,24 @@
+## TODO (high priority pending)
+- [ ] Create a personal CDN on VPS using SSH + Nginx to serve static assets (images, HTML, JS) so that Grok / browse_page tools can directly access them without crawling or conversion issues
+  - [ ] Subtask: Set up VPS and SSH access
+  - [ ] Subtask: Install and configure Nginx for static file serving
+  - [ ] Subtask: Implement security measures (e.g., firewall, SSL/TLS, access controls)
+  - [ ] Subtask: Upload and organize static assets
+  - [ ] Subtask: Test with previous image test case and verify direct access via tools
+- [ ] Create publish_agent.js in agents/ for secure deployment of documents to remote VPS (Nginx + ~/htdocs or /var/www/htdocs). Features: persistent config for multiple VPS (SSH host, port, user, htdocs path, http base URL), ask for missing endpoints on first use, generate long/obscure/randomized filenames for privacy (especially sensitive files), clean old/unused files in htdocs, rsync or scp with safety, support for static publishing of docs/markdown/html. Integrate with memory_agent for config persistence if possible. High privacy focus.
+
+## In Progress
+(none)
+
+## Later (future tasks)
+(none)
+
+## Done
+- [x] Document and review the "agent dave websocket protocol". Focus on communication between lib/AgentServer.js (central hub), lib/AgentClient.js (agent connections), and lib/wsIO.js (user interaction). Include description of the protocol, sequence diagrams if possible, and optimization suggestions.
+  - [x] Subtask: Review and analyze source files (AgentServer.js, AgentClient.js, wsIO.js)
+  - [x] Subtask: Summarize findings from review - Protocol uses JSON messages with 'action' from fixed ACTIONS list, bidirectional query/response with IDs for matching, introduction for registration, user_* for CLI/WS interaction, reset handling with epoch, pending response map with timeout. Suggestion: Add sequence diagram in Mermaid and document in docs/agent-dave-websocket-protocol.md.
+  - [x] Subtask: Document the protocol structure and message formats
+  - [x] Subtask: Create sequence diagrams for key interactions (Mermaid diagrams added to the new docs file)
+  - [x] Subtask: Identify and suggest optimizations for performance and reliability (detailed section added with 6 categories of improvements)
+
+Older tasks archived on 2026-04-20 to docs/todo-archive-v0.0.9.md. Previous archives: docs/todo-archive-v0.0.8.md (2026-04-15), docs/todo-archive.md (2026-04-13).

package/agents/code_agent.js

@@ -24,7 +24,7 @@ if (args['secret']) {
 // Set properties only if provided via command line (except model which has default)
 if (args['model'] || true) { // model gets default value
 	// @ts-ignore
-	options.model = args['model'] || 'grok-4-1-fast-reasoning';
+	options.model = args['model'] || 'grok-4.20-reasoning';
 }
 // if (args['temperature']) {
 	options.temperature = 0.2;
@@ -35,14 +35,14 @@ if (args['tokens']) {
 if (args['top_p']) {
 	options.top_p = parseFloat(args['top_p']);
 }
-const reasoning = args['reasoning'] ? args['reasoning'] : 'medium';
-if (reasoning) {
-	options.reasoning = {
-		// @ts-ignore
-		effort:reasoning,
-		summary: 'auto'
-	}
-}
+// const reasoning = args['reasoning'] ? args['reasoning'] : 'medium';
+// if (reasoning) {
+// 	options.reasoning = {
+// 		// @ts-ignore
+// 		effort:reasoning,
+// 		summary: 'auto'
+// 	}
+// }
 const toolsetMode = 'auto';
 const contextWindow = args['context'] ? parseInt(args['context']) : 2565000;
 

package/bin/dave.js

@@ -118,9 +118,9 @@ if (args.clear) {
 		};
 		options.tools.push({ type: 'web_search' });
 		options.tools.push({ type: 'x_search' });
-		options.model = args.model || 'grok-4-1-fast-reasoning';
+		options.model = args.model || 'grok-4.20-reasoning';
 		options.temperature = 0.2;
-		options.reasoning = { effort: 'medium', summary: 'auto' };
+		// options.reasoning = { effort: 'medium', summary: 'auto' };
 
 		const prompt = `
 Respond briefly and directly, using minimal words. Reason step-by-step first. Focus solely on core point; avoid elaboration or follow-ups. If unclear, ask clarifying questions before proceeding.

package/docs/agent-dave-websocket-protocol.md

@@ -0,0 +1,180 @@
+# Agent Dave WebSocket Protocol
+
+**Version**: 0.0.8 (as of April 2026)  
+**Repository**: https://codeberg.org/duin/hello-dave  
+**Core Files**:
+- `lib/AgentServer.js` — Central hub, registers agents as dynamic tools, handles user interactions and sessions.
+- `lib/AgentClient.js` — Agent-side wrapper (Prompt + ToolSet), queue-based message processor, auto-reconnect, epoch-based reset handling.
+- `lib/wsIO.js` — One-shot WS client for CLI tools (`dave --connect`, `wsio()` helper).
+
+## Overview
+
+The protocol enables **multi-agent collaboration** over WebSocket. 
+
+- A central **AgentServer** listens on `ws://127.0.0.1:<port>/ws`.
+- **AgentClient** instances connect, introduce themselves, and get registered as **dynamic tools** in the server's `ToolSet`.
+- The server exposes these agents to the main Prompt, allowing the LLM to call them like any other tool (`agent_query` / `agent_response`).
+- **User/CLI interaction** uses `user_*` actions (via `wsIO.js` or `dave` CLI).
+- All messages are **JSON** objects with an `action` field validated against a fixed list.
+- **Authentication**: `?wssrc_id=<secret>` query param (plain in AgentServer, base64 in wsIO.js).
+- **Reset handling**: Broadcast `reset`, clients use an `#epoch` counter to invalidate in-flight work.
+- **Response matching**: Uses `id` (timestamp-based) + pending map on server.
+
+This design turns specialized agents (code, todo, memory, readme, etc.) into callable tools while supporting direct CLI, interactive REPL, and one-shot queries.
+
+## Message Format
+
+Every message is a JSON object:
+
+```json
+{
+  "action": "one_of_the_actions_below",
+  "content": "string or object (varies)",
+  "id": "unique_timestamp_string_or_number",
+  "name"?: "agent_name_on_introduction"
+}
+```
+
+### Supported Actions (ACTIONS array in AgentServer.js)
+
+**Agent ↔ Server (Tool Calls)**
+- `agent_introduction` — Agent registers itself (sends `name` + `description`).
+- `agent_query` — Server calls an agent tool with natural language `content` (query).
+- `agent_response` — Agent returns result.
+- `agent_error` — Agent reports failure.
+
+**User/CLI ↔ Server**
+- `user_introduction` — CLI connects (sent by wsIO.js).
+- `user_request` — User query to main prompt.
+- `server_response` — Final answer from main prompt.
+- `server_error` — Error from main prompt.
+- `user_reset` — Reset current session.
+- `user_sessionlist` — Request list of saved sessions.
+- `user_loadsession` — Load a previous session.
+- `user_info` — Get server/prompt/session info.
+
+**Server → Clients (broadcasts/responses)**
+- `reset` — Broadcast to all agents on reset.
+- `server_reset`, `server_sessionlist`, `server_sessionloaded`, `server_info` — Responses to user actions.
+
+Unknown actions cause immediate client disconnection.
+
+## Key Interactions & Sequence Diagrams
+
+### 1. Agent Registration & Tool Call
+
+```mermaid
+sequenceDiagram
+    participant AgentClient
+    participant AgentServer
+    participant Prompt/ToolSet
+
+    AgentClient->>AgentServer: WS connect + ?wssrc_id=secret
+    AgentClient->>AgentServer: {action: "agent_introduction", name: "code", content: "Code execution agent..."}
+    AgentServer->>ToolSet: add("code", description, schema, handler)
+    Note over ToolSet,AgentServer: Tool now available to LLM
+
+    Prompt->>ToolSet: LLM decides to call "code" with query
+    ToolSet->>AgentServer: handler(query) → Promise
+    AgentServer->>AgentClient: {action: "agent_query", id: "1745...", content: "Write a bash script..."}
+    AgentClient->>AgentClient: #queue.push(), #processOne()
+    AgentClient->>Prompt: prompt.call(query)
+    AgentClient->>AgentServer: {action: "agent_response", id: "1745...", content: "```bash ...```"}
+    AgentServer->>Prompt: resolve(promise)
+    Prompt->>LLM: Continue with tool result
+```
+
+### 2. User One-Shot Query (via wsIO.js or dave --connect)
+
+```mermaid
+sequenceDiagram
+    participant CLI (wsIO)
+    participant AgentServer
+    participant Prompt
+
+    CLI->>AgentServer: WS connect + wssrc_id
+    CLI->>AgentServer: {action: "user_introduction", id: X}
+    CLI->>AgentServer: {action: "user_request", id: Y, content: "Hello Dave"}
+    AgentServer->>Prompt: prompt.call("Hello Dave")
+    Prompt->>LLM: Full reasoning + tool calls (may call registered agents)
+    Prompt-->>AgentServer: Final content
+    AgentServer->>CLI: {action: "server_response", id: Y, content: "..."}
+    CLI->>CLI: resolve promise, close WS
+```
+
+### 3. Reset Handling
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant AgentServer
+    participant AgentClient
+
+    User->>AgentServer: {action: "user_reset"}
+    AgentServer->>Prompt: prompt.reset()
+    AgentServer-->>All Agents: broadcast {action: "reset"}
+    AgentClient->>AgentClient: #epoch++, #queue=[], prompt.reset()
+```
+
+## Implementation Details
+
+- **Server-side pending responses**: `pendingResponses` Map keyed by `${conn.id}:${msg.id}` with timeout via `setInterval` (30s intervals, max 20 → 10min).
+- **Client-side queue**: Strict sequential processing (`#processing` guard, 2s polling interval by default). Prevents race conditions in tool calls.
+- **Auto-reconnect**: AgentClient retries every 5s on close.
+- **Session Management**: Integrated with `Session.js` for `user_sessionlist` / `user_loadsession`.
+- **wsIO.js specifics**: Sends both `user_introduction` + action in one connection, matches response by `id`, then closes. Uses base64 secret.
+
+## Optimizations & Suggestions
+
+**Current Strengths**
+- Simple JSON, no complex framing.
+- Epoch prevents stale responses after reset.
+- Dynamic tool registration — agents can be added at runtime.
+
+**Potential Improvements**
+1. **Performance**:
+   - Replace polling interval in AgentClient with event-driven queue (e.g. `setImmediate` or microtask after each message).
+   - Use a proper request-response correlation library or WebSocket subprotocol.
+   - Add backpressure handling for high-volume tool calls.
+
+2. **Reliability**:
+   - Heartbeat/ping-pong to detect dead connections faster than timeout.
+   - Exponential backoff on reconnect.
+   - Persistent message IDs (UUID instead of timestamp).
+   - Schema validation for all incoming messages (e.g. Zod or JSON Schema).
+
+3. **Observability**:
+   - Add structured logging (instead of console.log).
+   - Metrics: active clients, avg response time, error rate.
+   - OpenTelemetry or Prometheus integration.
+
+4. **Security**:
+   - Current secret is weak (query param). Consider JWT or mTLS for production.
+   - Rate limiting per connection.
+   - Validate `content` size.
+
+5. **Extensibility**:
+   - Support binary messages for large data (e.g. images, files).
+   - Add `agent_stream` for streaming responses from agents.
+   - Formalize as a subprotocol (`Sec-WebSocket-Protocol: agent-dave-v1`).
+
+6. **Documentation**:
+   - Generate Mermaid diagrams automatically from code comments.
+   - Add protocol test suite in `scenarios/`.
+
+**Next Steps** (from TODO):
+- Complete sequence diagrams (expand the Mermaid examples above).
+- Identify specific performance bottlenecks via profiling.
+- Create formal spec with error codes and versioning.
+
+## References
+
+- `lib/AgentServer.js`
+- `lib/AgentClient.js`
+- `lib/wsIO.js`
+- `agents/spawn_agent.js` (uses this protocol for hybrid/server/client modes)
+- `docs/multi-agent-clusters.md`
+- `docs/prompt/spawn_agent.md`
+
+*Last updated: April 20, 2026*  
+*This document was generated as part of the TODO task "Document and review the 'agent dave websocket protocol'."*

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