@j-o-r/hello-dave 0.1.1 → 0.1.4

package/CHANGELOG.md

@@ -1,25 +1,42 @@
-## 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/.
-- **bin/codeDave Fix**: Resolved SCRIPT_DIR symlink resolution for global npm bin runs from any dir (standard readlink loop idiom). Tested from /tmp/otherdir.
-- **Types Regeneration**: `npm run types` → full types/*.d.ts updated via tsc.
-- **Docs Added/Updated**: docs/generic-toolset.md (toolsPool/examples), docs/jsdoc-best-practices.md, docs/multi-agent-clusters.md (spawn_agent PM2), docs/prompt/spawn_agent.md (PROCESS/blueprint), docs/todo-archive.md (TODO history).
-- **NPM Deps & Scripts**: Pruned extraneous, installed missing (@j-o-r/apiserver/cli, gpt-3-encoder). Clean `npm ls`. TODO.md shortened (recent 7 Done items; older archived).
-- **utils/search_sessions.sh**: Added/modified for history search.
-- **Tests & Fixes**: genericToolset.test.js notes (write_file validation stable). write_file temp-first + cleanup for deploys. All spawn_agent changes verified in CodeServer cluster (PM2 hello-dave_*_9000).
-- **Release Prep**: package.json v0.0.7, git commits/tags. Ready for `npm publish --access public`.
-
-### v0.0.6 (Released - April 2026)
-[Previous content unchanged]
-
-[... rest of previous sections unchanged ...]
-
-Full history in git tags.
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive plan for **Agent File-Socket Communication Layer** (`docs/plans/agent-file-socket-communication.md`).
+  - Enables persistent agent sessions via Unix domain sockets in `.cache/sockets/`.
+  - One-shot calls participate in live sessions (same as interactive CLI).
+  - Bi-directional control plane (queries, commands, handoff, reset, info, list_agents, etc.).
+  - Any UI/frontend can attach to a running agent.
+  - "Keep it simple" mandate: `AgentLauncher` always ensures the socket server; CLI evolves to be a socket client.
+- Updated project documentation to reflect the new direction:
+  - `docs/project-overview.md`
+  - `docs/bin-dave.md`
+  - `TODO.md` (detailed tracking section with phases, open decisions, next actions)
+
+### Architecture Notes
+- Builds directly on the existing clean `Agent` + `AgentLauncher` + in-process handoff model (fresh context only).
+- Leverages `Prompt` as EventEmitter for natural event streaming over sockets.
+- No changes to existing agents or core behavior yet (planning + docs phase complete).
+- Legacy WS/swarm model remains in `_legacy/` and is not revived.
+
+See the plan document for full details, phased rollout, risks, and recommended next steps (Phase 1: minimal socket server/client + one-shot path).
+
+---
+
+## [0.1.3] - 2026-06 (prior)
+
+### Added / Changed
+- Unified `Agent` class + `AgentLauncher` with clean in-process handoff (`hand_over` / `load_agent` tools).
+- Fresh handoff semantics (no history copied; only system prompt + short task-focused context).
+- Self-reset support for deliberate fresh starts.
+- Dual-layer documentation model (framework vs project-local `docs/`).
+- `dave` CLI delegates almost everything to `AgentLauncher`.
+- Many agent improvements and toolset work.
+
+(Older history summarized; see git log for full details.)

package/README.md

@@ -1,242 +1,102 @@
-# hello-dave
+# @j-o-r/hello-dave
+
+![Selfie with HAL 9000](assets/selfie-hal9000.png)
 
 [![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)
-[![PM2 Compatible](https://img.shields.io/badge/PM2-Compatible-orange.svg)](https://pm2.keymetrics.io/)
-
-## 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.
-- **Music Toolsets**: Dedicated Stability AI (Stable Audio 3) and Minimax (Music 2.6/Cover) toolsets for text-to-music, audio transformation, inpainting, covers, lyrics, and more. See [docs/music-toolsets.md](docs/music-toolsets.md) for full details, tools, and agent examples.
-- **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.
-- **Multi-Agent Clusters**: PM2-powered CodeServer for scalable, clustered agent deployments (e.g., code_agent + todo_agent). Defaults to port 9000/secret '123'. See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md) for configuration.
-
-## 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). References [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md) for setup and scaling.
-
-- **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). See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
-
-- **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)) and multi-agent guides (e.g., [multi-agent-clusters.md](docs/multi-agent-clusters.md)).
-  - New: [music-toolsets.md](docs/music-toolsets.md) — Documentation for Stability and Minimax MusicToolsets with usage examples from agents/stability.js and agents/minimax.js.
-- **release/**: Build artifacts.
-
-Other files: `package.json`, `CHANGELOG.md`, `TODO.md`, `LICENSE`.
-
-## Installation
-
-1. **Prerequisites**: Node.js >= 20. PM2 for multi-agent clusters: `npm install -g pm2`.
-
-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:
+
+**'Hello, Dave.'** — A calm, reliable ESM toolkit for building and running AI agents with unified access to Grok (xAI), OpenAI, and Anthropic.
+
+## Quick Start
+
+```bash
+npm install -g @j-o-r/hello-dave
+
+dave --help
+dave --list-agents
+dave ask_agent
+dave code_agent "Refactor lib/Session.js"
+echo "Explain this error" | dave ask_agent
+```
+
+## Core Usage
+
 ```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
+dave <agent_name>                 # interactive
+dave <agent_name> "your message"  # one-shot
+echo "message" | dave <agent_name>
+dave <agent_name> --info
+dave --list-agents
 ```
 
-For full options, see script headers or run with `--help`.
+Agents are `*_agent.js` files discovered via `AgentLauncher`.
+
+## Agent Handoffs (Current Multi-Agent Model)
+
+Use the built-in `hand_over` / `load_agent` tools for clean in-process delegation to specialists (or self-reset with fresh context).
+
+- Always fresh: target gets only its own system prompt + short task-focused context.
+- No history is copied.
+- Use `list_agents` first when unsure.
+
+This replaced the older WebSocket server/client/swarm/CodeServer model (which has been abandoned).
+
+See `docs/creating-agents.md` for details.
 
-### Programmatic Usage
+## Creating Agents
 
-Import and use in your Node.js app:
-```javascript
-import { AgentManager } from '@j-o-r/hello-dave';
-// Setup and run agent...
+```bash
+dave agent_creator "Create a weather_agent..."
+dave agent_creator "Improve code_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).
-
-### CodeServer & PM2 Multi-Agent (v0.0.8)
-
-CodeServer (via `bin/codeDave` or `agents/codeserver.sh`) launches scalable, PM2-clustered multi-agent environments for collaborative tasks (e.g., code generation + task management). It deploys agents like `code_agent`, `todo_agent`, and `readme_agent` on a WebSocket server, enabling chaining and load balancing.
-
-- **Defaults**: Port 9000, secret '123' (customizable via args).
-- **Prerequisites**: Install PM2 globally (`npm install -g pm2`).
-- **Quickstart**:
-  ```bash
-  codeDave 9000 --secret 123  # Launches PM2 cluster on ws://127.0.0.1:9000/ws
-  pm2 list  # Verify processes (e.g., code_agent, todo_agent instances)
-  echo "task" | bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123  # One-shot query to cluster
-  ```
-  This starts the cluster, lists running agents, and sends a test task (response routed to available agents).
-
-- **Scaling & Management**: Use PM2 commands (e.g., `pm2 scale <app> 4`, `pm2 stop all`). For ecosystem config, PM2 JSON files, or agent orchestration, see the [full guide in docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
-
-- **Integration**: Combine with `spawn_agent.js` for dynamic agent addition to clusters (e.g., spawn new agents and connect via `--connect ws://127.0.0.1:9000/ws`).
-
-## 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 9000 '123'  # Or use codeDave 9000 --secret 123
-  # Connects code_agent, todo_agent, readme_agent, etc., to the server on ws://127.0.0.1:9000/ws.
-  # Test: pm2 list; echo "Optimize this code" | dave --connect ws://127.0.0.1:9000/ws --secret 123
-  # For advanced config: See [docs/multi-agent-clusters.md](docs/multi-agent-clusters.md).
-  ```
-
-- **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.
+**Follow the current standard**: [docs/creating-agents.md](docs/creating-agents.md)
 
-## Development
+Key pattern:
+- `export default agent;`
+- `new Agent({ prompt, api, call_name, call_description, ... })`
+- Register tools + `toolset.borrow(API.toolset.generic.handoff)`
+
+## Documentation
+
+- **[docs/creating-agents.md](docs/creating-agents.md)** — Canonical guide (read this first for agent work).
+- `docs/bin-dave.md`
+- `docs/project-overview.md`
+- `docs/docs-organization.md`
+- `docs/toolset.md` etc.
 
-- **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`
+**Legacy docs** (old WS/swarm/CodeServer patterns) live in `docs/_legacy/`. They are retained for historical reference only.
 
-Use `git status` and `ls` to inspect changes. Ensure ESM compatibility.
+## Programmatic Usage
 
-## Contributing
+```js
+import { Agent, API, AgentLauncher } from '@j-o-r/hello-dave';
 
-Contributions welcome! Fork the repo, create a branch, and submit a pull request to https://codeberg.org/duin/hello-dave.
+const agent = new Agent({
+  prompt: "...",
+  api: API.chat.xai,
+  call_name: 'my_agent',
+  call_description: '...'
+});
 
-- Report bugs: https://codeberg.org/duin/hello-dave/issues
-- Follow Apache-2.0 license.
+const launcher = new AgentLauncher();
+await launcher.load('code_agent');
+await launcher.run();
+```
+
+## Development
+
+```bash
+npm install
+npm run link-self
+```
 
 ## License
 
-This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
+Apache-2.0
+
+Repository: https://codeberg.org/duin/hello-dave
 
 ---
-*Repository: https://codeberg.org/duin/hello-dave*
----
+
+*Putting itself to the fullest possible use.*

package/TODO.md

@@ -1,35 +1,173 @@
-## High Priority Pending
-- [ ] 2026-05-04: Create simple event-based unified WebSocket architecture. Remove complicated streaming plan. Focus on live reasoning in CLI/WS, unify user/agent client handling in AgentServer.js, make Prompt events broadcast consistently to user WS connections. Make code more readable and logical. Reference: docs/plans/simple-event-driven-websocket.md.
-  - [ ] Review current WebSocket protocol and Prompt event emitters.
-  - [ ] In AgentServer.js: Centralize event listeners for Prompt, add unified broadcast method for user WS, unify user/agent client handling.
-  - [ ] Update lib/wsIO.js for CLI to handle events similarly to WS.
-  - [ ] Refactor code for readability and logical flow.
-  - [ ] Test end-to-end: Event flow from Prompt to user display in CLI and WS.
-  - [ ] Update docs/websocket-protocol.md with new architecture.
-
-- [ ] 2026-05-04: Implement unified lib/Agent.js that treats users and agents symmetrically. Key rules: No 'final response' concept. Use Prompt 'ready' event as completion signal. Agents can send 'function_call' requests to user connections (user acts as expert/tool). Update message protocol to be fully event-driven with 'ready' as end marker. Reference: docs/plans/unified-agent-architecture.md.
-  - [ ] Review current Agent.js, AgentServer.js, and Prompt event system.
-  - [ ] Refactor lib/Agent.js to unify user and agent handling: shared methods for event emission, listening, and protocol adherence.
-  - [ ] Integrate Prompt 'ready' event as the primary completion hook across agents and user interactions.
-  - [ ] Add support for agents to emit 'function_call' events to user WS connections.
-  - [ ] Update message protocol: Define event types, ensure 'ready' is broadcast consistently.
-  - [ ] Test symmetry: Verify bidirectional flows (agent-to-user function calls, user-to-agent events) in CLI/WS.
-  - [ ] Document in docs/websocket-protocol.md and update any related docs.
-
-## Prompt & Agent Quality (High Priority)
-- [ ] 2026-04-25: Review all prompts (in agents, spawn_agent, memory protocol, etc.) to prevent over-complicating implementations by adding unrequested requirements (e.g. backward compatibility when user explicitly says the project is BETA v0.0.x and does not need it).
-
-## Multi-modal
-- [ ] 2026-04-25: Implement multi-modal (audio, images, video) capabilities to the CLI.
-
-## Agent Improvements
-- [ ] 2026-04-25: Teach/instruct the spawn_agent to test and improve agents in a 'server' setting.
-
-## Input Handling
-- [ ] 2026-04-25: Create a 'smart' pre-evaluation agent that assesses user input for clarity before the main agent starts work. It should check: Is the task clear? Are the necessary tools present? Guess context from previous messages if input seems incomplete (e.g. accidental early enter).
-
-## API Capabilities
-- [ ] 2026-04-25: Ensure 'hello-dave' is fully capable of implementing/improving other APIs following the exact structure and patterns of this project (tools, agents, memory protocol, etc.).
-
-## Done
-(none - all archived to docs/todo-archive-v0.1.0.md on 2026-04-24)
+# TODO
+
+[ ] [investigate openshell](https://docs.nvidia.com/openshell/about/overview)
+
+## Agent Loader Review Follow-up (`lib/agentLoader.js`) — TODO
+
+Context: Review of `lib/agentLoader.js` identified several correctness and maintainability issues around agent instance freshness, discovery side effects, path containment, and API/schema consistency.
+
+### Priority 1 — Fresh agent instances for handoff/reset correctness
+
+**Problem**:
+- `loadAgent()` imports ESM modules directly and returns singleton default exports as-is.
+- Because ESM modules are cached, repeated loads of singleton-exported agents return the same object.
+- This conflicts with the intended fresh handoff / self-reset behavior in `AgentLauncher`.
+- Verified behavior during review:
+  - `loadAgent('echo_agent')` twice returned the same object.
+  - Both calls shared the same prompt and session objects.
+
+**Tasks**:
+- [ ] Decide and document the official agent module contract:
+  - Recommended: loadable agents should export a factory that creates a fresh `Agent` instance.
+  - Example: `export default function createAgent() { return new Agent(...) }`.
+  - Optional named form: `export function createAgent() { ... }`.
+- [ ] Update `lib/agentLoader.js` to prefer fresh factories:
+  - [ ] Prefer `mod.createAgent` when present.
+  - [ ] Then support function default exports as factories.
+  - [ ] Treat singleton object exports as legacy compatibility only.
+- [ ] Decide whether singleton object exports should:
+  - [ ] Produce a warning in development / verbose mode, or
+  - [ ] Continue silently for backward compatibility, or
+  - [ ] Be rejected in a future breaking release.
+- [ ] Update bundled agents that currently export singleton `Agent` instances to export factories instead.
+- [ ] Audit all files in `agents/*.js` and any example/custom agents in docs.
+- [ ] Update documentation in `docs/creating-agents.md` to clearly show the factory export pattern.
+- [ ] Update any README/examples that currently show singleton agent exports.
+
+**Suggested tests**:
+- [ ] Add a `node:test` case proving two calls to `loadAgent('some_agent')` return different `Agent` instances.
+- [ ] Add assertions that their prompt/session instances are also distinct where applicable.
+- [ ] Add a regression test for same-agent reset / handoff to confirm no old session object is reused.
+
+**Acceptance criteria**:
+- [ ] Repeated `loadAgent(name)` calls produce fresh instances for factory-based agents.
+- [ ] Same-agent handoff/reset does not reuse the previous `Agent`, `Prompt`, or `Session` object.
+- [ ] Legacy singleton behavior, if retained, is explicitly documented as non-fresh.
+
+### Priority 2 — Make `listAgents()` side-effect-light
+
+**Problem**:
+- `listAgents()` currently imports candidate agent modules and may call exported functions to get descriptions.
+- This can execute top-level module code, construct full agents, run top-level await, perform I/O, hang, or seed the ESM module cache before actual loading.
+- Discovery should ideally be cheap and not instantiate agents.
+
+**Tasks**:
+- [ ] Define a lightweight metadata contract for agent descriptions.
+  - Recommended exports:
+    - `export const call_description = '...'`
+    - `export const description = call_description`
+- [ ] Update `listAgents()` so it reads exported metadata without calling agent factories.
+- [ ] Avoid invoking default exports during discovery.
+- [ ] Decide fallback behavior when metadata is missing:
+  - [ ] Return `[NO DESCRIPTION]`, or
+  - [ ] Return `[ERROR]`, or
+  - [ ] Use filename-derived fallback text.
+- [ ] Update bundled agents to export metadata constants directly.
+- [ ] Update docs to tell agent authors that descriptions used by `dave --agents` / `list_agents` must be exported as metadata.
+
+**Suggested tests**:
+- [ ] Add a fixture agent whose factory throws if called.
+- [ ] Confirm `listAgents()` still lists it from metadata without calling the factory.
+- [ ] Add a fixture with top-level metadata and ensure the listed description matches exactly.
+- [ ] Add a fixture with missing metadata and verify the selected fallback behavior.
+
+**Acceptance criteria**:
+- [ ] `listAgents()` does not call agent factories.
+- [ ] Discovery remains fast and predictable.
+- [ ] Listing agents does not accidentally create or cache live agent instances.
+
+### Priority 3 — Harden name-based path resolution against symlink escapes
+
+**Problem**:
+- Direct path loading performs realpath/root containment checks.
+- Name-based resolution currently checks readability of candidate files but does not apply equivalent realpath containment validation.
+- A symlink inside an allowed agent directory could point outside the intended search roots and still be imported.
+
+**Tasks**:
+- [ ] Add shared helper logic for path containment checks so direct-path and name-based loading use the same security rule.
+- [ ] Realpath each configured agent directory once where practical.
+- [ ] When resolving by agent name, verify the resolved candidate file is inside one of the allowed real agent directories.
+- [ ] Decide whether symlinked files inside the allowed tree are permitted when their real target also remains inside an allowed root.
+- [ ] Improve error messages for symlink escape attempts.
+
+**Suggested tests**:
+- [ ] Add a temporary test fixture with an agent symlink that points outside the allowed agent directory.
+- [ ] Confirm `loadAgent(name)` rejects the symlink escape.
+- [ ] Add a positive test for a normal in-tree agent.
+- [ ] If in-tree symlinks are allowed, add a positive test for a symlink whose real target remains inside the allowed root.
+
+**Acceptance criteria**:
+- [ ] Name-based loading cannot import files outside configured agent roots via symlinks.
+- [ ] Direct-path and name-based resolution enforce consistent containment semantics.
+
+### Priority 4 — Align agent-name validation rules across loader and handoff tool schema
+
+**Problem**:
+- `lib/agentLoader.js` allows names matching `^[a-z0-9_]{2,}$`.
+- `lib/handOffToolset.js` advertises `^[a-z0-9_]{2,64}$`.
+- This means some names are loadable/discoverable but cannot be called through `hand_over` / `load_agent`.
+
+**Tasks**:
+- [ ] Centralize the public agent-name regex in a shared module or exported constant.
+- [ ] Decide the canonical limit; recommended: `^[a-z0-9_]{2,64}$`.
+- [ ] Update `lib/agentLoader.js` to use the shared rule.
+- [ ] Update `lib/handOffToolset.js` to use the same source of truth or generate the schema pattern from it.
+- [ ] Update docs for allowed agent names.
+
+**Suggested tests**:
+- [ ] Add tests for too-short, valid, invalid-character, and too-long agent names.
+- [ ] Confirm loader and handoff schema accept/reject the same examples.
+
+**Acceptance criteria**:
+- [ ] There is one canonical public agent-name rule.
+- [ ] Loader behavior and tool schema behavior are consistent.
+
+### Priority 5 — Clarify or improve direct relative path resolution
+
+**Problem**:
+- Direct relative paths are currently resolved against `process.cwd()`.
+- That is reasonable for CLI use, but may surprise callers using `createAgentLoader({ from: import.meta.url })`, who may expect relative paths to resolve from the caller package root.
+
+**Tasks**:
+- [ ] Decide whether direct relative paths should remain CWD-relative or become caller-package-root-relative when `from` is provided.
+- [ ] If keeping current behavior:
+  - [ ] Document clearly that direct relative paths are always CWD-relative.
+  - [ ] Add tests proving that behavior.
+- [ ] If changing behavior:
+  - [ ] Resolve relative direct paths from the `from` package root when provided.
+  - [ ] Preserve current CLI behavior where no `from` is provided.
+  - [ ] Add migration notes for any compatibility impact.
+
+**Suggested tests**:
+- [ ] Add tests for direct relative path loading from the project CWD.
+- [ ] Add tests for `createAgentLoader({ from: import.meta.url })` from a nested fixture package.
+- [ ] Add tests for invalid relative direct paths and outside-root attempts.
+
+**Acceptance criteria**:
+- [ ] Path resolution behavior is intentional, documented, and covered by tests.
+
+### Priority 6 — Documentation and examples cleanup
+
+**Tasks**:
+- [ ] Update agent creation docs to show fresh factory exports and metadata exports together.
+- [ ] Include a minimal recommended agent template:
+  - [ ] `export const call_description = '...'`
+  - [ ] `export const description = call_description`
+  - [ ] `export default function createAgent() { return new Agent(...) }`
+- [ ] Add a short compatibility note for legacy singleton exports if they remain supported.
+- [ ] Update CLI/help docs that mention `list_agents`, `hand_over`, or agent naming constraints.
+- [ ] Add a short security note about agent path resolution and symlink containment.
+
+### Priority 7 — Validation checklist after implementation
+
+Run and record results for the following after changes are made:
+
+- [ ] `node --check lib/agentLoader.js`
+- [ ] `node --check lib/handOffToolset.js`
+- [ ] Project test script from `package.json`, if available.
+- [ ] Focused `node:test` suite for agent loader behavior.
+- [ ] Manual smoke test:
+  - [ ] `dave --agents` or equivalent listing command.
+  - [ ] Load the same factory-based agent twice and confirm fresh objects.
+  - [ ] Trigger same-agent handoff/reset and confirm the old session object is not reused.
+