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

package/README.md.bak

@@ -1,218 +0,0 @@
-# hello-dave
-
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Node.js >=20](https://img.shields.io/badge/Node.js-%3E=20-green.svg)](https://nodejs.org/)
-[![Version: v0.0.8](https://img.shields.io/badge/Version-v0.0.8-green.svg)](https://codeberg.org/duin/hello-dave)
-
-## Table of Contents
-
-- [Description](#description)
-- [Features](#features)
-- [Folder Structure](#folder-structure)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Usage Examples](#usage-examples)
-- [Development](#development)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Description
-
-**hello-dave** is an ESM (ECMAScript Modules) toolkit for building AI agents with unified access to endpoints from Grok (xAI), OpenAI, and Anthropic. It provides CLI tools for interacting with agents locally or via WebSocket servers, along with pre-built agent scripts for various tasks like code generation, documentation, testing, and more.
-
-The project emphasizes modular agent management, tool integration (e.g., web search, file operations), and session handling with memory and caching. With v0.0.8, enhanced portability allows spawning agents in isolated environments like `/tmp` while maintaining tool functionality relative to the current working directory (CWD).
-
-## Features
-
-- **Unified API Access**: Seamless integration with xAI (Grok), OpenAI, and Anthropic models.
-- **CLI Tools**: `dave` for querying agents, `agentDave` for spawning servers, `codeDave` for code servers.
-- **Agent Scripts**: Specialized agents for code, docs, npm, todo, readme, memory, and more.
-- **WebSocket Support**: Connect to remote agent servers for interactive or one-shot interactions.
-- **Toolsets**: Built-in tools for search, file I/O, email, and custom toolcalls.
-- **Session Management**: Cache history, search sessions, reset, and inspect logs.
-- **ESM-First**: Modern Node.js modules with TypeScript definitions.
-- **Portable Agent Spawning**: `spawn_agent.js` enables creating and deploying agents anywhere (project dirs or fresh `/tmp`). Supports auto-deploy in existing projects (detects `./agents/*.js`), manual code+bash in isolated setups. Tools adapt to CWD for portability. Hybrid modes combine server/client for chaining. See [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) for blueprint and validation.
-
-## Folder Structure
-
-- **bin/**: Executables for CLI tools.
-  - `dave.js`: Main CLI for asking agents or connecting to WebSocket servers.
-  - `spawn_agent.js`: Spawns agent instances (binary: `agentDave`).
-  - `codeDave`: Launches code servers (via PM2 clusters).
-
-- **agents/**: Agent scripts (`*_agent.js`) for specific tasks. These can be run directly with `node agents/<script>.js`.
-  - `ask_agent.js`: General query agent.
-  - `code_agent.js`: Code generation and execution agent (serves as main server in code clusters).
-  - `daisy_agent.js`: Specialized agent (details in script).
-  - `docs_agent.js`: Documentation-focused agent.
-  - `gpt_agent.js`: OpenAI GPT integration agent.
-  - `grok_agent.js`: xAI Grok-specific agent.
-  - `memory_agent.js`: Agent with enhanced memory and context handling.
-  - `npm_agent.js`: NPM package management agent.
-  - `prompt_agent.js`: Prompt engineering and testing agent.
-  - `readme_agent.js`: README.md management agent.
-  - `spawn_agent.js`: Agent spawner (also in bin/). Creates portable CLI/WS agents + PM2 launchers. Validates/tests/deploys to `./agents/<name>.js`. Supports hybrid server/client modes. Portable to `/tmp` (tools follow CWD). Blueprint: [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md).
-  - `test_agent.js`: Testing and validation agent.
-  - `todo_agent.js`: TODO list and task management agent.
-  - `codeserver.sh`: Shell script for launching PM2-based code server clusters (uses agents above).
-
-- **lib/**: Core library modules (e.g., `index.js`, `wsCli.js`, `wsIO.js`, API integrations).
-- **scenarios/**: Test and example scenarios (e.g., toolset tests, integration scripts).
-- **types/**: TypeScript definitions.
-- **utils/**: Utility scripts (e.g., session management, testing).
-- **docs/**: Additional documentation, including agent blueprints (e.g., [prompt/spawn_agent.md](docs/prompt/spawn_agent.md)).
-- **release/**: Build artifacts.
-
-Other files: `package.json`, `CHANGELOG.md`, `TODO.md`, `LICENSE`.
-
-## Installation
-
-1. **Prerequisites**: Node.js >= 20.
-
-2. **Local Development**:
-   ```bash
-   git clone https://codeberg.org/duin/hello-dave.git
-   cd hello-dave
-   npm install
-   ```
-
-3. **Global CLI Installation** (for `dave`, `agentDave`, `codeDave`):
-   ```bash
-   npm install -g .
-   # Or link for dev: npm run link-self
-   ```
-
-4. **API Keys**: Set environment variables (e.g., `XAIKEY` for xAI, `OPENAI_API_KEY` for OpenAI).
-
-## Usage
-
-### CLI Tools
-
-- **dave**: Interact with agents locally or remotely.
-  - Local query: `dave --ask "Predict the weather"`
-  - One-shot remote: `echo "Hello" | dave --connect 'ws://127.0.0.1:8080' --secret '123'`
-  - Interactive remote: `dave --connect 'ws://127.0.0.1:8080' --secret '123'`
-  - Other: `dave --list` (sessions), `dave --clear` (cache), `dave --help`.
-
-- **agentDave**: Spawn an agent server (powered by `spawn_agent.js`).
-  ```bash
-  agentDave --serve 8080 --secret '123'  # Starts WebSocket server
-  ```
-
-- **codeDave**: Launch a PM2 code server cluster.
-  ```bash
-  codeDave 8080 --secret '123'  # Or: dave --code 8080 --secret '123'
-  ```
-
-### Running Agents
-
-Run agent scripts directly:
-```bash
-node agents/spawn_agent.js --serve 8080 --secret '123'  # Spawn server
-node agents/code_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'  # Client mode
-```
-
-For full options, see script headers or run with `--help`.
-
-### Programmatic Usage
-
-Import and use in your Node.js app:
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-// Setup and run agent...
-```
-
-### spawn_agent.js Specifics (v0.0.8 Portability Ready)
-
-`spawn_agent.js` (executable as `agentDave`) creates and deploys portable agents in CLI, WebSocket server, client, or **hybrid** modes (server + client for tool chaining). It fetches live prompts from [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) and validates new agents via blueprint (temp files, syntax checks, grep for modes/tools).
-
-- **Modes**:
-  - **Direct (One-Shot)**: Positional input, e.g., `node agents/spawn_agent.js "Create a tester"`.
-  - **Interactive CLI**: No input; runs REPL-like session.
-  - **Server**: `--serve <port>` – Exposes as remote tool (e.g., for other agents to call `spawn_agent`).
-  - **Client**: `--connect <ws_url>` – Connects to remote server for tool access.
-  - **Hybrid**: `--serve <port> --connect <ws_url>` – Serves locally while using remote tools.
-
-- **Portability**:
-  - **In Project**: Auto-deploys to `./agents/<name>.js` if `./agents/*.js` exist (uses existing structure).
-  - **Fresh /tmp**: Manual code generation + bash setup (e.g., `mkdir /tmp/myproj/agents; cd /tmp/myproj; node spawn_agent.js ...`). Tools (e.g., `read_file`) follow CWD, ensuring isolation without fixed paths.
-  - Works in any dir; no repo deps beyond Node.js + npm installs.
-
-- **Custom Tools**: Specify in prompt, e.g., "name=coderev, tools=read_file,web_search,execute_bash_script".
-
-For validation/testing: See blueprint in [docs/prompt/spawn_agent.md](docs/prompt/spawn_agent.md) (includes bash examples like `node agents/NEW_AGENT.js --help` or server connect tests).
-
-## Usage Examples
-
-- **Direct Spawn (Project)**:
-  ```bash
-  cd hello-dave  # Or any project with ./agents/
-  node agents/spawn_agent.js "Create code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file,execute_bash_script,web_search"
-  # Deploys to ./agents/coderev_agent.js; test: node agents/coderev_agent.js "Review this diff"
-  ```
-
-- **/tmp Workflow (Portable, Fresh Setup)**:
-  ```bash
-  mkdir -p /tmp/myportable/agents
-  cd /tmp/myportable
-  # Copy or fetch spawn_agent.js (e.g., curl from repo or npm install @j-o-r/hello-dave)
-  npm init -y && npm i @j-o-r/hello-dave @j-o-r/sh
-  node spawn_agent.js "Create todo agent: name=todo, desc=Task manager, tools=read_file,write_file"
-  # Deploys to ./agents/todo_agent.js; tools use /tmp/myportable as CWD
-  node agents/todo_agent.js --serve 8081 --secret abc  # Test server mode
-  ```
-
-- **Hybrid Mode with Custom Tools**:
-  ```bash
-  node agents/spawn_agent.js --serve 8081 --connect ws://127.0.0.1:8080/ws --secret abc "Spawn a docs agent with custom email tool"
-  # Serves on 8081 (exposes new agent), connects to 8080 (gains remote tools like email)
-  # Test: In another term, node agents/spawn_agent.js --connect ws://127.0.0.1:8081/ws --secret abc "Use the new docs agent"
-  ```
-
-- **Spawn a Server**:
-  ```bash
-  node agents/spawn_agent.js --serve 8080 --secret '123'
-  # Then connect: echo "Task" | dave --connect 'ws://127.0.0.1:8080' --secret '123'
-  ```
-
-- **Launch Code Cluster** (includes multiple agents):
-  ```bash
-  node agents/codeserver.sh 8080 '123'  # Or use codeDave
-  # Connects code_agent, todo_agent, readme_agent, etc., to the server.
-  ```
-
-- **Local Agent Query** (no server):
-  ```bash
-  dave --ask --model 'grok-4-1-fast-reasoning' "Write a function"
-  ```
-
-- **Custom Agent**:
-  ```bash
-  node agents/docs_agent.js --connect 'ws://127.0.0.1:8080' --secret '123'
-  ```
-
-See `scenarios/` for more test scenarios.
-
-## Development
-
-- **Build Types**: `npm run types`
-- **Test**: `npm run tests` (runs `utils/test.sh`)
-- **Release**: `npm run release` then `npm run publish`
-- **Local Linking**: `npm run link-self` / `npm run unlink-self`
-
-Use `git status` and `ls` to inspect changes. Ensure ESM compatibility.
-
-## Contributing
-
-Contributions welcome! Fork the repo, create a branch, and submit a pull request to https://codeberg.org/duin/hello-dave.
-
-- Report bugs: https://codeberg.org/duin/hello-dave/issues
-- Follow Apache-2.0 license.
-
-## License
-
-This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
-
----
-*Repository: https://codeberg.org/duin/hello-dave*
----