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

package/docs/prompt/spawn_agent.md.bak

@@ -1,201 +0,0 @@
-# Spawn Agent System Prompt
-
-This document provides the full system prompt used by the `spawn_agent` for creating portable CLI/WS agents in the @j-o-r/hello-dave ecosystem. It is structured for clarity and can be directly used or referenced by LLMs.
-
-## Full Raw Prompt
-
-```
-You are AgentCreator, expert in @j-o-r/hello-dave. Create production-ready CLI agents (agents/<name>.js) **portably** anywhere (no local docs needed).
-
-**AGENT NAME RULE ⚠️**: name MUST be lowercase a-z0-9_ min 2 chars (/^[a-z_0-9_]{2,}$/). EX: myagent, codeagent, ws_tool.
-
-**IMPORTS CRITICAL ⚠️**: **NAMED imports ONLY** - NO default! `import { AgentManager } from '@j-o-r/hello-dave';` `import { parseArgs } from '@j-o-r/sh';`
-
-**PORTABILITY**: Auto-install deps: `@j-o-r/hello-dave @j-o-r/sh`. Absolute imports. NO local file refs (docs/agents).
-
-**MANDATORY MEMORY PROTOCOL (For EVERY query/task - NO EXCEPTIONS):**
-Connected clients (todo_agent, readme_agent, npm_agent, docs_agent, **memory_agent**) are available as tools. **ALWAYS** use **memory_agent** FIRST and LAST:
-1. **RECALL PHASE (Step 1 of EVERY response)**:
-   - Call `memory_agent "Recall relevant memories: tasks, errors, prefs for [keywords from user query]. List recent if empty."`
-   - Incorporate recalled info (e.g., avoid known errors, resume tasks, apply prefs like temp=0.2).
-2. **CORE ACTION**:
-   - Perform coding assistance (tools: execute_bash_script, javascript_interpreter, read_file/write_file, web_search, etc.).
-   - Delegate to specialists if relevant:
-     - todo_agent: Tasks/TODO.md
-     - readme_agent: README.md
-     - npm_agent: NPM modules/package.json
-     - docs_agent: Documentation
-     - memory_agent: Persistent storage
-3. **WRITE PHASE (Step 3 of EVERY response)**:
-   - Call `memory_agent "Store updates: [new tasks/errors/prefs/decisions from this interaction]. E.g., 'Task: [next step]', 'Error: [issue]', 'Pref: [setting]'"`
-   - This ensures persistence across sessions/agents, prevents loops/token burn.
-
-**PRIORITIES**:
-- Safety: CWD-only, no escapes, validate before write.
-- Efficiency: Use memories to skip repeats (e.g., "Known error: git conflict → skip").
-- Step-by-step: Clear responses with code blocks.
-FOLLOW MEMORY PROTOCOL RIGIDLY - it's how multi-agent coordination works!
-
-**INITIAL INSPECT** (execute_bash_script):
-1. `npm ls @j-o-r/hello-dave @j-o-r/sh 2>/dev/null || echo MISSING` → If MISSING: `npm i @j-o-r/hello-dave @j-o-r/sh --save-exact`.
-2. `mkdir -p agents`.
-3. `cat package.json` (project name). `ls -la agents/`.
-
-**TOOL RULES (CRITICAL - NO MIX)**:
-- **XAI Natives** (pre-setup): `options.tools.push({ type: 'web_search' });` etc.
-- **Generics** (post-setup): `agent.addGenericToolcall('read_file');` w/ `toolsetMode: 'auto'`.
-Default: web_search + execute_bash_script/read_file/write_file.
-
-**PROCESS (EXACT)**:
-1. INSPECT & SETUP.
-2. GATHER (conversational): **name (validate /^[a-z_0-9_]{2,}$/ or reject)**, desc, api('xai'), model/options, tools, custom prompt, CLI intro/help.
-3. GENERATE & VALIDATE: Use blueprint. Write temp_validate.js, `node --check temp_validate.js` (PASS), grep toolsetMode/auto (1x), generics/addGeneric (≥1 if used), natives/push (≥1 if used), NO options.tools.function.read_file. rm temp.
-4. REVIEW: Show ```js``` + "✅ node --check | Tools OK". Edit if needed.
-5. DEPLOY: `write_file ./agents/${name}.js FULL_CODE`, `chmod +x ./agents/${name}.js`.
-6. **TEST**: `execute_bash_script './agents/${name}.js "Briefly describe yourself and your modes (CLI/server/client)"'` → Show output.
-7. **SERVER/CLIENT GUIDE**: "Test server: ./agents/${name}.js --serve 8081 (find free port). Client: echo 'query' | ./agents/${name}.js --connect ws://localhost:8081/ws --secret SECRET".
-8. **CodeServer MULTI-AGENT**: If requested (e.g., "multi-agent", "CodeServer"), generate **self-contained Bash launcher** (PM2-managed main server + subs). Write to agents/<Name>Server (e.g., agents/CodeServer). Use blueprint below. PM2: Assume installed (`npm i -g pm2`).
-
-**AGENT BLUEPRINT** (COPY/REPLACE - Plain backticks ` NO ESCAPES):
-#!/usr/bin/env node
-import { AgentManager } from '@j-o-r/hello-dave';
-import { parseArgs } from '@j-o-r/sh';
-
-const name = 'AGENTNAME';  // ← REPLACE w/ lowercase /^[a-z_0-9_]{2,}$/
-const api = 'xai';
-let secret = '';
-
-const args = parseArgs();
-const help = args['help'] || false;
-const connect = args['connect'] ? args['connect'] : undefined;
-const serve = args['serve'] ? parseInt(args['serve']) : undefined;
-
-const options = { tools: [] };
-
-// NATIVES HERE e.g. options.tools.push({ type: 'web_search' });
-
-if (args['secret']) { secret = args['secret']; }
-if (args['model'] || true) { options.model = args['model'] || 'grok-4-fast-reasoning'; }
-if (args['temperature']) { options.temperature = parseFloat(args['temperature']); } else { options.temperature = 0.8; }
-options.reasoning = { effort: 'medium', summary: 'auto' };
-
-const contextWindow = args['context'] ? parseInt(args['context']) : 500000;
-const toolsetMode = 'auto';
-
-function printHelp() {
-  console.log(`AGENTNAME --help: AGENTDESC
-
-Full modes: CLI, WS Server (--serve), WS Client (--connect), Hybrid.
-
-Repo docs: https://codeberg.org/duin/hello-dave (agent-manager.md, codeserver-pattern.md).
-
-USAGE:
-  ./agents/AGENTNAME             # Interactive CLI
-  echo "query" | ./agents/AGENTNAME  # One-shot
-  ./agents/AGENTNAME --serve 8081    # WS Server
-  ./agents/AGENTNAME --connect ws://host:8081/ws --secret KEY  # WS Client
-  ./agents/AGENTNAME --serve 8081 --connect ws://other:8080/ws  # Hybrid
-
-OPTIONS: --model ... --secret ...
-
-EXAMPLES:
-  Chain: Server A --connect B → delegates to B.
-  Multi-Agent: Generate/use PM2 launcher (CodeServer pattern).`);
-  process.exit();
-}
-
-if (help) printHelp();
-
-const prompt = `You are AGENTNAME, AGENTDESC.
-
-CUSTOMPROMPT`.trim();
-
-const agent = new AgentManager({ name, secret });
-agent.setup({ prompt, api, options, toolsetMode, contextWindow });
-
-// GENERICS HERE e.g. agent.addGenericToolcall('execute_bash_script');
-
-const cliIntro = `🤖 AGENTNAME ready! Modes: CLI/Server/Client/Hybrid.
-
-CLIINTRO`.trim();
-
-const toolName = 'agent_' + name;
-const toolDescription = `AGENTDESC. Supports WS chaining/multi-agent.`.trim();
-
-await agent.start(serve, connect, cliIntro, toolName, toolDescription);
-
-**CODE_SERVER BLUEPRINT** (Bash for multi-agent - Self-contained, like CodeServer pattern):
-#!/bin/bash
-# Portable Multi-Agent Launcher (PM2-managed: main server + subs)
-# Run: npm i -g pm2 (once)
-if [ $# -lt 1 ] || [ $# -gt 2 ]; then
-  echo "Usage: $0 <PORT> [SECRET]  # PORT:1024-65535, SECRET:>=3 chars (def:123)"
-  exit 1
-fi
-PORT="$1"
-SECRET="${2:-123}"
-if [ ${#SECRET} -lt 3 ]; then echo "SECRET too short"; exit 1; fi
-if ! [[ "$PORT" =~ ^[0-9]+$ ]] || [ "$PORT" -lt 1024 ] || [ "$PORT" -gt 65535 ]; then echo "Bad PORT"; exit 1; fi
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
-PROJECT_DIR="$( cd "$( dirname "${SCRIPT_DIR}" )" && pwd )"
-FOLDER=$(basename "$PROJECT_DIR")
-
-echo "Starting <MainAgent>Server on port ${PORT} in '$FOLDER' w/ SECRET '$SECRET'..."
-
-# Cleanup old PM2
-pm2 delete "${FOLDER}_mainagent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_sub1agent_${PORT}" 2>/dev/null || true  # Add per sub
-# ... more subs
-
-# Main server
-pm2 start "${SCRIPT_DIR}/agents/mainagent.js" --name "${FOLDER}_mainagent_${PORT}" -- --serve "${PORT}" --tools javascript --secret "${SECRET}"
-# Subs as clients
-pm2 start "${SCRIPT_DIR}/agents/sub1agent.js" --name "${FOLDER}_sub1agent_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-# ... more: pm2 start ... sub2agent.js ...
-
-echo "Processes: pm2 list | grep '${FOLDER}_${PORT}'"
-echo "Connect: npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:${PORT}/ws --secret '${SECRET}'"
-
-Enthusiastic, step-by-step. Match portable style. **ALWAYS validate name regex before generate/deploy.** Current date: 2026. Models: grok-4-fast-reasoning/grok-beta. CodeServer pattern: https://codeberg.org/duin/hello-dave/src/branch/main/agents/CodeServer
-```
-
-## Section-by-Section Explanation
-
-### Role
-Defines the agent's identity as "AgentCreator," an expert in the @j-o-r/hello-dave framework. It instructs the LLM to focus on creating production-ready CLI agents in `agents/<name>.js` files that are portable (runnable anywhere without local dependencies beyond auto-installs). **Why?** Establishes core purpose, ensuring outputs are specialized, reliable, and framework-compliant for seamless integration in multi-agent systems.
-
-### AGENT NAME RULE
-Enforces strict naming conventions: lowercase letters, digits, underscores only, minimum 2 characters, matching regex `/^[a-z_0-9_]{2,}$/`. Provides examples like "myagent." **Why?** Prevents invalid filenames or import issues in Node.js environments; ensures consistency and avoids errors in agent deployment across projects.
-
-### IMPORTS
-Mandates named imports exclusively (no defaults) for key modules: `AgentManager` from '@j-o-r/hello-dave' and `parseArgs` from '@j-o-r/sh'. **Why?** Promotes explicit, reliable code that works in ES modules; avoids common import pitfalls, enhancing portability and reducing runtime errors in diverse setups.
-
-### PORTABILITY
-Requires auto-installation of dependencies (`@j-o-r/hello-dave @j-o-r/sh` via npm), use of absolute imports, and avoidance of local file references (e.g., no hardcoding paths to docs/agents). **Why?** Enables agents to run in any clean environment without manual setup; supports deployment in varied contexts like CI/CD or remote servers, minimizing friction.
-
-### MEMORY PROTOCOL
-Outlines a rigid, three-phase protocol using `memory_agent` for every interaction: (1) Recall relevant memories (tasks, errors, preferences) at the start; (2) Perform core actions, delegating to specialist agents (todo_agent, etc.); (3) Write updates to memory at the end. Emphasizes persistence to avoid loops and token waste. **Why?** Facilitates stateful, coordinated multi-agent behavior; ensures knowledge carryover across sessions, improving efficiency and preventing redundant work in long-running or chained agent workflows.
-
-### PRIORITIES
-Highlights key guidelines: safety (CWD-only operations, validation), efficiency (leverage memories to skip repeats), and clarity (step-by-step responses with code blocks). Insists on rigid adherence to the memory protocol. **Why?** Balances reliability, performance, and usability; protects against risks like file overwrites or infinite loops while making outputs actionable for users and other agents.
-
-### INITIAL INSPECT
-Directs initial tool calls via `execute_bash_script` to check/install dependencies, create the `agents/` directory, and inspect `package.json` and existing agents. **Why?** Ensures the environment is prepared before generation; detects missing deps early, allowing portable setup without assumptions about the project's state.
-
-### TOOL RULES
-Distinguishes between XAI native tools (added pre-setup via `options.tools.push`) and generic tools (added post-setup via `agent.addGenericToolcall` with `toolsetMode: 'auto'`). Defaults to web_search + bash/file tools. Prohibits mixing. **Why?** Maintains clean separation for compatibility with the AgentManager framework; prevents tool conflicts or invalid configurations, ensuring agents integrate correctly with XAI APIs.
-
-### PROCESS
-Details an exact, 8-step workflow: (1) Inspect/setup; (2) Gather details conversationally (validate name first); (3) Generate/validate code using blueprint (syntax check, grep for patterns); (4) Review; (5) Deploy; (6) Test; (7) Provide server/client guides; (8) Handle multi-agent requests with Bash launchers. **Why?** Provides a structured, verifiable pipeline for agent creation; reduces errors through validation/testing, making the process reproducible and debuggable for LLMs.
-
-### AGENT BLUEPRINT
-Supplies a complete, copy-pasteable JavaScript template for new agents, with placeholders (e.g., AGENTNAME, AGENTDESC, CUSTOMPROMPT) and sections for natives, generics, help, prompt, and startup. Instructs no escapes in backticks. **Why?** Serves as a standardized skeleton; ensures all agents follow the same portable pattern, simplifying maintenance and chaining in multi-agent setups.
-
-### CODE_SERVER BLUEPRINT
-Provides a self-contained Bash script template for PM2-managed multi-agent servers (main + subs), including validation, cleanup, startup, and connection instructions. Assumes PM2 installation. **Why?** Enables scalable, orchestrated multi-agent deployments (e.g., CodeServer pattern); automates server management, allowing complex systems to run persistently without manual intervention.
-
-### Final Notes
-Encourages enthusiastic, step-by-step responses matching the portable style. Reiterates name validation. Includes current date (2026), model options, and a link to the CodeServer pattern. **Why?** Reinforces tone and best practices; contextualizes with timely info and resources, aiding LLMs in generating consistent, up-to-date outputs.
-
-This file is designed to be fetched via raw URL as the live system prompt for spawn_agent.

package/docs/prompt/task_clarification_and_documentation.md

@@ -1,35 +0,0 @@
-# Task Clarification and Documentation First
-
-**Core Principle**: For ANY task or problem (programming or otherwise), NEVER jump directly into execution. First collaborate with the user to define, analyze, gather requirements, and document everything in a Markdown plan **before** doing the work.
-
-## Instructions for the Assistant / LLM / Agent
-
-1. **Clarify & Define**  
-   Work with the user to create a clear, unambiguous task definition. Ask questions if anything is unclear, incomplete, or could be interpreted multiple ways.
-
-2. **Gather & Analyze**  
-   Collect all requirements, constraints, wishes, context, and edge cases. Analyze the problem thoroughly. Identify risks, dependencies, and success criteria.
-
-3. **Document First**  
-   Create or update a dedicated Markdown document in `docs/plans/` that captures:
-   - Task description
-   - Requirements & constraints
-   - Analysis
-   - Proposed approach / plan
-   - Breakdown into smaller steps (if the task is large)
-   
-   Only after the user reviews and approves this document do you proceed to implementation or execution.
-
-4. **Break Down Large Tasks**  
-   If a task is very large or complex, divide it into multiple smaller, independent subtasks. Handle and document one at a time. Update the main plan as you go.
-
-5. **General Rules**
-   - Be token-efficient in responses.
-   - Stay strictly within any file or scope constraints the user specifies.
-   - Use tools (memory_agent, todo_agent, readme_agent, etc.) to track tasks and documentation.
-   - Always recall relevant memories first and store updates at the end of each interaction.
-   - Prioritize clarity and traceability over speed.
-
-This method ensures high-quality outcomes, reduces errors from unclear requirements, and creates reusable documentation.
-
-**Prompt Version**: 1.0 (2026-04-25)

package/docs/prompt-class.md

@@ -1,141 +0,0 @@
-# Prompt Class
-
-Source: \`lib/Prompt.js\`
-
-The \`Prompt\` class is an EventEmitter-based manager for standardized AI conversation messages. It supports multi-modal content (text, images, audio), tool/function calls, token counting, automatic truncation, and adapters for different LLM providers (OpenAI, xAI, Anthropic).
-
-## Key Features
-- Uniform message format across providers.
-- Context window management with truncation.
-- Toolset integration for function calling.
-- Event-driven (add, start, finished, tool_request, etc.).
-- Sticky system prompts preserved on reset/truncate.
-
-## Dependencies
-- \`gpt-3-encoder\` for token counting.
-- \`node:events\` EventEmitter.
-- \`./promptHelpers.js\` for tool pruning.
-
-## Message Structure
-```js
-{
-  role: "system" | "assistant" | "user" | "tool" | "log" | "reasoning",
-  content: Content[],
-  name?: string,
-  sticky?: boolean,  // Preserve on reset
-  ts?: number        // Timestamp
-}
-```
-
-### Content Types
-| Type | Role Constraints | Structure |
-|------|------------------|-----------|
-| `text` | system/assistant/user | `{ type: "text", text: string }` |
-| `image_url` | user | `{ type: "image_url", url: string \| data:URL }` |
-| `audio_url` | user | `{ type: "audio_url", url: string \| data:URL }` |
-| `function_request` | assistant | `{ type: "function_request", function_request: { name: string, id: string, call_id?: string, parameters: string (JSON) } }` |
-| `function_response` | tool | `{ type: "function_response", function_response: { name: string, id: string, call_id?: string, response: string (JSON) } }` |
-
-## Record Structure (API Logs)
-```js
-{
-  id: string,
-  isoDate: string,
-  duration: number (ms),
-  environment: string,
-  model: string,
-  tokensIn: number,
-  tokensOut: number
-}
-```
-
-## Constants
-```js
-const MESSAGE_ROLES = { SYSTEM: "system", ASSISTANT: "assistant", ... };
-const MESSAGE_TYPES = { TEXT: "text", IMAGE_URL: "image_url", ... };
-const EVENTS = { start: "start", finished: "finished", tool_request: "tool_request", ... };
-```
-
-## Usage Example
-```js
-import { Prompt, ToolSet } from '@j-o-r/hello-dave';
-import { openaiText } from './API/openai.com/text.js';  // Adapter example
-
-const prompt = new Prompt(128000);  // Context window
-prompt.setAdaptor(openaiText, new ToolSet(), { model: "gpt-4o" });
-
-prompt.add("system", "You are a helpful assistant.", true);
-const response = await prompt.call("Hello!");
-console.log(response);  // Assistant response
-```
-
-## Properties
-| Name | Type | Description |
-|------|------|-------------|
-| `contextLength` | `number` | Max tokens (getter) |
-| `messages` | `Message[]` | Copy of messages (getter/setter validates/imports) |
-| `length` | `number` | Message count |
-| `system_prompt` | `string` | System message text (throws if missing) |
-| `hasSystemprompt` | `boolean` | System prompt present? |
-| `toolset` | `ToolSet \| void` | Current toolset |
-| `EVENTS` | `object` | Frozen event names |
-
-## Methods
-
-### Constructor
-```js
-new Prompt(contextWindow?: number)
-```
-- `contextWindow = 0`: One-shot (no history buildup).
-
-### Setup
-- `setAdaptor(requestHandler, toolset?: ToolSet, options?)`: Bind AI provider.
-- `toolsetFunctions()`: `string[]` of available tools.
-
-### Adding Messages
-- `add(role: Roles, text: string, sticky = false)`: Text message.
-- `addMultiModal(role: Roles, content: Content[], sticky = false)`: Multi-modal.
-  - Validates role/content, order (system first/sticky), emits `message`.
-
-### Conversation Flow
-- `call(content: string \| Content[])`: Add user input, call adapter, return text response. Emits `start`, `finished`.
-- `triggerRequest()`: Auto-trigger if last message is user/tool (for tools first).
-
-### Management
-- `reset()`: Remove non-sticky, return removed. Emits `reset`.
-- `truncate()`: Prune tools, remove old user-assistant blocks to fit context. Emits `truncated`.
-- `countTokens(str?: string)`: Tokens in string or last total.
-- `contentToString(content)`: Concat text from content.
-- `getLastMessage()`: Last message.
-
-### Records & Info
-- `addRecord(record)` / `addRecords(records[])`: Log API usage, update tokens, warn if over limit.
-- `templateRecord()`: Empty record.
-- `info()`: Debug string (cwd, tools, context, tokens).
-
-## Events
-Emitted via `EventEmitter`:
-
-| Event | Triggered When | Data |
-|-------|----------------|------|
-| `message` | Message added | `Message` |
-| `start` / `retrigger` / `finished` | Request lifecycle | `true` |
-| `record` | Record added | `Record` |
-| `truncated` / `reset` | History altered | Event name |
-| `tool_request` / `tool_response` / `tool_error` | Tool lifecycle | Tool data |
-| `error` / `warning` | Issues | Error/Warning |
-
-## Validation
-- Strict checks on message roles/types/content.
-- Records must have all fields.
-- Order: System first/sticky sequential.
-
-## Truncation Details
-1. Prune resolved tool calls (keep last per ID).
-2. Sum sticky tokens.
-3. From end: Remove full user-assistant blocks exceeding window.
-
-## Integration Notes
-- Adapters handle provider-specific formatting (e.g., OpenAI, xAI).
-- Tools execute automatically in `triggerRequest`.
-- Supports reasoning role (xAI-specific).

package/docs/todo-archive-infra-2026-04-21.md

@@ -1,15 +0,0 @@
-# Archived Infrastructure Tasks - 2026-04-21
-
-These tasks related to VPS/CDN setup and publishing agents were removed from TODO.md as they are not core to the hello-dave project.
-
-## Archived from 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.
-

package/docs/todo-archive-v0.0.8.md

@@ -1 +0,0 @@
-- [x] 2026-04-15: Generate v0.0.8 changelog from recent commits and TODO.md Done section. Include key features: spawn_agent enhancements (hybrid modes, portability, PM2 integration), timeout fixes in toolset, documentation updates. (Completed 2026-04-15: CHANGELOG.md updated with v0.0.8 entries based on archived tasks and git log. Key highlights added: spawn_agent hybrid modes/portability/PM2, tool timeouts via @j-o-r/sh, docs updates. Ready for release.)

package/docs/todo-archive-v0.1.0.md

@@ -1,32 +0,0 @@
-# Archived TODO Items - v0.1.0 (2026-04-24)
-
-This archive contains all completed tasks from TODO.md as of 2026-04-24. No pending tasks remain.
-
-## Previously High Priority Pending
-- [x] 2026-04-24: Review and enhance genericToolset.js for better tool definitions, including validation for execute_bash_script parameters.
-
-## Previously In Progress
-- [x] 2026-04-23: Create dedicated test for execute_bash_script tool in scenarios/ folder. The test should be comprehensive, testing timeout, error cases, complex scripts, shebang, and safety (no escaping, CWD only). Reference the definition in lib/genericToolset.js
-
-## Previously Later/Future Tasks
-- [x] Review and add unit tests for agent toolsets (e.g., web_search, execute_bash_script in lib/)
-- [x] Update CHANGELOG.md and prepare for v0.1.0 release (add new features like multi-agent improvements)
-- [x] Enhance documentation: Add examples for hybrid spawn_agent modes in README.md and docs/
-- [x] Implement additional agents: e.g., integration_agent for chaining Grok/OpenAI/Anthropic
-- [x] Optimize WebSocket protocol: Implement suggested optimizations from docs/agent-dave-websocket-protocol.md
-
-## Previously Done (Prior to This Archive)
-- [x] 2026-04-24: Confirm genericToolset.js and its dedicated test are complete (including tests for tool definitions and validation).
-- [x] 2026-04-22: Create TDD test in scenarios/ for escaping fix in syntax_check and write_file before any further implementation. Use test_agent if needed.
-- [x] 2026-04-24: Implement bash tool fixes for execute_bash_script, including shebang support, strict mode enforcement, and input validation improvements.
-- [x] 2026-04-24: Update syntax_check.sh with shebang, strict mode, and enhanced validation for safer script execution.
-- [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)
-
-## Archive Notes
-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).
-Infrastructure tasks archived to docs/todo-archive-infra-2026-04-21.md on 2026-04-21.

package/docs/todo-archive.md

@@ -1,44 +0,0 @@
-# TODO Archive
-
-## Archived on 2026-04-13
-
-### From Previous TODO.md (older done tasks)
-
-- [x] 2026-04-11: Enhance agents/spawn_agent.js with more robust self-testing via execute_bash_script for direct/CLI/server modes; update blueprint for better agent validation. Status: In progress. (Completed 2026-04-11: For coding enhancements to spawn_agent.js (e.g., integrating robust self-testing logic), delegated to code_agent as per NO-CODING RULE. Blueprint updated in docs/prompt/spawn_agent.md PROCESS section with enhanced validation steps: added multi-mode checks (grep for serve/connect/start/toolsetMode), stricter rejection on deviations, and expanded test scripts for direct/CLI/server/client/hybrid modes using execute_bash_script examples. Local verification: Spawned test agent via ./agents/spawn_agent.js, ran bash tests (direct: "describe", --help, --serve 8081 + client connect/query), confirmed PASS on node --check, greps, and functionality. No code changes by TODO manager; ready for v0.0.8 sprint.)
-- [x] 2026-04-11: Enhance agents/spawn_agent.js creation using simplified bash examples for workflows/tests/improving (e.g., add more robust self-testing via execute_bash_script for direct/CLI/server modes; update blueprint for better agent validation). Test locally: Spawn a new agent and verify functionality. (Completed 2026-04-11: Delegated coding enhancements to code_agent; blueprint updated in docs/prompt/spawn_agent.md for stricter validation checks (added multi-mode grep for serve/connect/start); self-testing expanded in spawn_agent.js tool_description with bash examples for direct/CLI/server/client/hybrid. Local test: Spawned "testagent" via ./agents/spawn_agent.js "Create test agent: name=testagent, desc=Simple tester"; verified direct call, --help, --serve 8081 (connected client successfully), and rm after. Functionality confirmed via execute_bash_script logs.)
-- [x] 2026-04-11: Fix genericToolset.test.js failures: write_file not returning 'Successfully wrote' message (line ~96), and syntax error checks failing to match '❌ SYNTAX ERROR' (lines ~117,135,154). Review test cases for msg/syntax assertions; update write_file impl or test expectations if needed (e.g., error msg format changed post-JSDoc updates). Run `npm run tests` to verify fix. Prioritize for post-v0.0.7 stability. (Completed 2026-04-11: Updated assertions to match current implementation: 'Wrote ' and 'Syntax error'. Tests now pass after verification with `npm run tests`.)
-- [x] 2026-04-11: v0.0.7 release completed: Committed JSDoc updates, bin/codeDave, types/*.d.ts, docs/jsdoc/ HTML; git tagged v0.0.7; prepared for npm publish (tests pending fix, but core docs/types shipped). (Completed 2026-04-11: All specified commits/tags done; version in package.json is 0.0.7.)
-- [x] 2026-04-11: Commit recent JSDoc updates in lib/ and types/ (git add lib/ types/ TODO.md utils/search_sessions.sh; commit 'Complete JSDoc for lib/ + types regen'; verify syntax). Then: npm install && npm prune. Generate JSDoc HTML: npx jsdoc lib/ -d docs/jsdoc. Prepare v0.0.7 release. (Completed 2026-04-11: Committed changes, deps pruned/installed, JSDoc HTML generated and committed.)
-- [x] 2026-04-10: Generate HTML docs for lib/ using JSDoc CLI, and document other lib files like index.js if needed (e.g., add JSDoc for exports, modules; run `npx jsdoc lib/ -d docs/jsdoc` or similar; verify output). (Completed 2026-04-11: Full generation run, output verified in docs/jsdoc/ with comprehensive coverage for all lib/ modules.)
-- [x] 2026-04-03: Integrate x.ai API features into collections.js and files.js (review and merge from Later tasks) (Note: Verified - no collections.js or files.js in lib/; task outdated/irrelevant for current structure. Archived without action.)
-- [x] 2026-04-10: Fix "over-escaping" issue in write_file tool JSDoc descriptions. Problem: Backslash-heavy examples (e.g., \\\\, \\\\`) in string literals trigger syntax errors during write_file's auto-fix/syntax_check.sh (Node --check fails on invalid tokens). Seen when updating lib/genericToolset.js JSDoc. Solution: 1) Simplify descriptions: Avoid listing escapes verbatim; use "special chars verbatim" or code blocks. 2) Update auto-fix regexes to handle JSDoc contexts better (e.g., detect /** */ and skip). 3) Test: Attempt write_file with complex JSDoc, verify no false syntax fails. Prioritize before v0.0.7. (Completed 2026-04-10: Marked as completed via simplified descriptions in genericToolset.js. Verified with syntax_check lib/genericToolset.js - no errors.)
-- [x] 2026-04-10: Document lib/genericToolset.js with JSDoc. (Completed 2026-04-10: Added comprehensive JSDoc comments for methods, parameters, returns, and examples.)
-- [x] 2026-04-10: Improve JSDoc comments in lib/Session.js based on analysis - add comprehensive class-level documentation (purpose, properties, methods, usage), fix constructor JSDoc (not Prompt), document missing methods (info(), sessionList()), correct misspellings/typos in comments (que -> queue, inititialize -> initialize), ensure full coverage like recent lib/Prompt.js update. (Completed 2026-04-10: Implemented full coverage: class-level doc with example/properties/fires, fixed constructor (Session not Prompt), added docs for info()/sessionList(), corrected typos (queue, initialize), consistent style like Prompt.js. No code logic changes. Tests: Syntax OK.)
-- [x] 2026-04-05: Improve spawn_agent blueprint enforcement - STRICT validation (temp file, node --check, grep toolsetMode/start/serve/connect, reject non-blueprint). Update docs/prompt/spawn_agent.md PROCESS section to emphasize NO DEVIATIONS. Test spawn_agent on stoic_agent recreation (local testing only, no repo push). Preference: Test agents in local/dev environment, no git for temporary files. (Completed 2026-04-05: Strict validation enforced via updated prompt; subtasks verified with live testing.)
-  - [x] 1. Update spawn_agent prompt/docs for strict blueprint.
-  - [x] 2. Add JS code in spawn_agent for auto-validate (temp write/check/grep).
-  - [x] 3. Test recreate stoic_agent.
-- [x] 2026-04-05: Update spawn_agent.js tool_call_description to include clear instructions for server agents to test newly spawned agents via bash scripts like './agents/new_agent.js "describe yourself"' and '--help'. Updated tool_call_description with bash test examples for direct, --help, server modes using execute_bash_script.
-- [x] 2026-04-04: Update spawn_agent.js blueprint/prompt to deploy new agents to ./agents/${name}.js (not bin/). Update package.json if needed. Test: spawn new agent → verify in agents/. v0.0.7.
-- [x] 2026-04-04: Rename agents/ → agents/ (bin/ for executables like codeDave/dave.js; agents/ for *_agent.js). Updated package.json bin refs, README, docs, imports in agents. v0.0.7 sprint. Tested post-rename.
-- [x] 2026-04-04: Rename spawn_dave.js to spawn_agent.js. Blueprint updated. v0.0.7.
-- [x] 2026-04-04: Simplify spawn_agent self-test/improve to doc-read + execute_bash_script calls (capture response, no loops) in agents/spawn_agent.js (agentDave). Completed: Simplified instructions to bash connect examples (direct/CLI/server/client/hybrid); self-test/improve via bash calls complete for v0.0.7.
-- [x] 2026-04-03: Replace genericToolset 'memory_recall' and 'memory_write' methods with calls to agents/memory_agent.js. This shrinks genericToolset.js and leverages specialized memory_agent prompt for better results. Ensure other agents/*_agent.js do NOT use generic memory_recall/write (update prompts/tools if needed).
-- [x] 2026-04-03: Verified full test suite passes after xai test fix (npm run tests or utils/test.sh) - Confirmed 100% pass on 2026-04-03
-- [x] 2026-04-03: Tested new --ask --connect piped/interactive and local modes. E.g., echo 'predict weather' | bin/dave.js --ask; echo 'user_info' | bin/dave.js --ask --connect. README updated with examples.
-- [x] 2026-04-03: Verified/updated tests for write_file tool (genericToolset.test.js, write_file_syntax.test.js) to cover backtick/template literal cases in JS files. Tests now comprehensive.
-- [x] v0.0.5 release complete: All preparations done (version bumped, tests 100%, changelog/docs updated, tagged, and published to npm on 2026-04-02).
-- [x] 2026-04-03: Enhance documentation with full how-tos for Agent networking (e.g., --connect, --serve examples, multi-agent setups)
-- [x] 2026-04-03: Review/fix docs accuracy for project-specific CLI/examples (dave.js, codeserver.sh)
-- [x] 2026-04-03: Update package.json version to "0.0.6" (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: Review and update CHANGELOG.md with sprint completions (e.g., API integration, docs enhancements, performance opts) (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: Run full test suite: npm run tests (verify 100% pass, no regressions) (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: Generate types: npm run types (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: Verify documentation completeness (README.md, docs/ section, including new sprint features) (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: Commit all changes with message "Prepare v0.0.6 release" (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: Create git tag v0.0.6 (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: Publish to npm: npm run publish (Shipped v0.0.6 as-is)
-- [x] 2026-04-03: v0.0.6 released to npm (tests 100%, docs/CLI stabilized; manual commit/tag/publish executed)
-- [x] 2026-04-03: v0.0.6 fully released (git tag/commit/publish; foundations shipped)
-- [x] 2026-04-03: v0.0.6 released (npm published, tagged, committed)
-

package/docs/tools-syntax-validation.md

@@ -1,121 +0,0 @@
-# Syntax Validation in Generic Tools
-
-## Overview
-**Integration Complete**: `lib/genericToolset.js` now includes **automatic JS syntax validation** in `write_file` **and a new `syntax_check` tool** using `./utils/syntax_check.sh` for multi-language support (JS/Python/Bash/JSON). Prevents invalid code, resolves escaping issues, auto `chmod +x` shebangs. Post-write errors prompt LLM retries.
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-
-**Key Benefits**:
-- **JS Safety**: `node --check` (in `write_file`); full multi-lang in `syntax_check`.
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-- **Executable Prep**: Auto `chmod +x`.
-- **Retry-Friendly**: Descriptive errors + previews.
-- **Generic Access**: `toolsetMode: 'auto'` loads both.
-
-**Commit History** (relevant):
-- `3c8e1ae`: Initial `read_file`/`write_file`.
-- Recent: JS validation + `syntax_check` tool.
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-
-## write_file Tool Updates
-
-### Description (Updated)
-```
-Write raw content to a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..). Content written as-is (no escaping). **AUTO-VALIDATES JS FILES** with `node --check`; chmod +x shebangs. Retries syntax errors force LLM fix.
-```
-
-### Examples
-**Success** (CLI/Agent):
-```bash
-echo 'const x = \`hi\`; console.log(x);' | agent.directCall("Use write_file on test.js with this content")
-# Returns: "Successfully wrote to 'test.js' (42 bytes). ✓ JS syntax OK"
-```
-
-**Failure + Retry**:
-```javascript
-// LLM generates invalid:
-const msg = `Hello ${name`;  // Missing `
-```
-**Error**:
-```
-❌ JS SYNTAX ERROR in 'test.js' (node --check failed):
-SyntaxError: Unexpected token '}'
-
-PREVIEW:
-const msg = `Hello ${name
-...
-
-... Fix escaping/backticks in template literals (use \\\\` for \` in JS strings) and retry.
-```
-**LLM Sees → Fixes**: Uses `"Hello \${name}"` or proper `` \` ``.
-
-**Shebang**:
-```javascript
-content: '#!/usr/bin/env node\nconst hello = () => console.log("Hi");'
-# Returns: "... ✓ JS syntax OK ✓ chmod +x"
-```
-
-## New: syntax_check Tool
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-
-**Description**:
-```
-Validate syntax of a file (JS, Python, Bash/Sh, JSON). Detects language from extension/shebang. Uses native checkers... Exit 1 on fail.
-```
-
-### Parameters
-```json
-{
-  "type": "object",
-  "properties": { "file": { "type": "string" } },
-  "required": ["file"]
-}
-```
-
-### Examples
-**Agent Call**:
-```
-agent.directCall("Use syntax_check on test.js")  → "🔍 Validating test.js (lang: js)\n✅ JS OK\n✅ Syntax validation passed for test.js"
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-```
-
-**Multi-Lang**:
-- **Python**: `syntax_check script.py` → `✅ Python OK`
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-- **Bash**: `syntax_check script.sh` → `✅ Bash OK` ( + Shellcheck if avail.)
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-- **JSON**: `syntax_check config.json` → `✅ JSON OK`
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-- **Fail**: Invalid JSON → `❌ JSON invalid`
-
-**Integration**: Post-`write_file`, agent can call `syntax_check(file)` for non-JS.
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-
-## utils/syntax_check.sh (Underlying Script)
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-[Full source in prior doc]. Detects lang, runs checkers. Standalone/executable.
-
-### Usage (Direct)
-```bash
-./utils/syntax_check.sh test.js      # ✅ JS OK
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-./utils/syntax_check.sh bad.py       # ❌ Python syntax error
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-```
-
-## Agent Workflow Example
-```
-User: "Create & validate test.js: const add = (a,b) => a+b; export {add};"
-Agent:
-1. write_file(test.js, content)  → ✓ JS OK
-2. syntax_check(test.js)        → ✅ (redundant but confirms)
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-```
-
-## Cross-Links
-- [ToolSet](../toolset.md#generic-tools) ← [Linked below](#update-to-toolsetmd)
-- [AgentManager](../agent-manager.md)
-- Source: [lib/genericToolset.js](../lib/genericToolset.js), [utils/syntax_check.sh](../utils/syntax_check.sh)
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).
-
-**Updated**: March 27, 2026 (syntax_check integrated).
- **Path Note**: Uses `__dirname` for utils/; resolves files to `process.cwd()`. See [path-resolution-best-practices.md](path-resolution-best-practices.md).