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

package/{examples → agents}/ask_agent.js

@@ -56,19 +56,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Your query here" [--options]
+./agents/${name}.js "Your query here" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'search_agent'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/codeserver.sh

@@ -25,23 +25,23 @@ FOLDER=$(basename "$PROJECT_DIR")
 echo "Starting CodeServer on port ${PORT} in folder '${FOLDER}' (SCRIPT_DIR: ${SCRIPT_DIR}) with SECRET '${SECRET}'..."
 
 # Delete existing processes with folder_port suffix
-pm2 delete "${FOLDER}_code_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_todo_agent_${PORT}"  2>/dev/null || true
-pm2 delete "${FOLDER}_readme_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_npm_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_docs_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_test_agent_${PORT}" 2>/dev/null || true
-pm2 delete "${FOLDER}_memory_agent_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_code_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_todo_${PORT}"  2>/dev/null || true
+pm2 delete "${FOLDER}_readme_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_npm_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_docs_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_test_${PORT}" 2>/dev/null || true
+pm2 delete "${FOLDER}_memory__${PORT}" 2>/dev/null || true
 
 # Spawn main Agent / server (absolute paths to scripts)
-pm2 start "${SCRIPT_DIR}/code_agent.js" --name "${FOLDER}_code_agent_${PORT}" -- --serve "${PORT}" --tools javascript --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/code_agent.js" --name "${FOLDER}_code_${PORT}" -- --serve "${PORT}" --tools javascript --secret "${SECRET}"
 # Attach clients
-pm2 start "${SCRIPT_DIR}/todo_agent.js"   --name "${FOLDER}_todo_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/readme_agent.js" --name "${FOLDER}_readme_agent_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/npm_agent.js"    --name "${FOLDER}_npm_agent_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/docs_agent.js"   --name "${FOLDER}_docs_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/test_agent.js"   --name "${FOLDER}_test_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
-pm2 start "${SCRIPT_DIR}/memory_agent.js"   --name "${FOLDER}_memory_agent_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/todo_agent.js"   --name "${FOLDER}_todo_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/readme_agent.js" --name "${FOLDER}_readme_${PORT}" -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/npm_agent.js"    --name "${FOLDER}_npm_${PORT}"    -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/docs_agent.js"   --name "${FOLDER}_docs_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/test_agent.js"   --name "${FOLDER}_test_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
+pm2 start "${SCRIPT_DIR}/memory_agent.js"   --name "${FOLDER}_memory_${PORT}"   -- --connect "ws://127.0.0.1:${PORT}/ws" --secret "${SECRET}"
 
 echo "CodeServer processes spawned with prefix '${FOLDER}_' and suffix _${PORT}. Check with: pm2 list | grep '${FOLDER}_${PORT}'"
 echo "dave --connect ws://127.0.0.1:${PORT}/ws --secret '$SECRET'"

package/{examples → agents}/daisy_agent.js

@@ -57,19 +57,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Generate lyrics for pop song" [--options]
+./agents/${name}.js "Generate lyrics for pop song" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'daisy_agent'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/docs_agent.js

@@ -54,19 +54,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Create a doc on Node.js basics" [--options]
+./agents/${name}.js "Create a doc on Node.js basics" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'agent_docs'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/gpt_agent.js

@@ -52,19 +52,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Your query" [--options]
+./agents/${name}.js "Your query" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'gpt_agent'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/grok_agent.js

@@ -64,19 +64,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "What is your task?" [--options]
+./agents/${name}.js "What is your task?" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL. Runs indefinitely until Ctrl+C.

package/agents/memory_agent.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs, SH } from '@j-o-r/sh';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+
+const name = 'memory_agent';
+const api = 'xai';
+let secret = '';
+
+const args = parseArgs();
+
+let input; // Directcall input (positional ONLY - NO pipe)
+if (args._.length === 1 && typeof args._[0] === 'string' && args._[0].trim() !== '') {
+	input = args._[0].trim();
+}
+
+const help = args['help'] || false;
+const connect = args['connect'] ? args['connect'] : undefined;
+const serve = args['serve'] ? parseInt(args['serve']) : undefined;
+
+/** @type {import('lib/API/x.ai/responses.js').XAIOptions} */
+const options = { tools: [] };
+options.tools.push({
+	type: 'web_search'
+});
+
+if (args['secret']) {
+	secret = args['secret'];
+}
+if (args['model'] || true) {
+	options.model = args['model'] || 'grok-4-fast-reasoning';
+}
+if (args['temperature']) {
+	options.temperature = parseFloat(args['temperature']);
+}
+if (args['tokens']) {
+	options.max_output_tokens = parseInt(args['tokens']);
+}
+if (args['top_p']) {
+	options.top_p = parseFloat(args['top_p']);
+}
+const reasoning = true;
+if (reasoning) {
+	options.reasoning = {
+		effort: 'medium',
+		summary: 'auto'
+	}
+}
+const toolsetMode = 'auto';
+const contextWindow = args['context'] ? parseInt(args['context']) : 250000;
+
+function printHelp() {
+	console.log(`'${name} --help' You are looking at it.
+
+## USAGE MODES:
+
+### 1. Direct Call (One-Shot, Positional ONLY):
+./agents/${name}.js "Recall tasks" [--options]
+
+### 2. Interactive CLI (no positional arg):
+./agents/${name}.js [--options]
+
+### 3. WS Server (no positional arg):
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
+
+### 4. WS Client (no positional arg):
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+
+### 5. Hybrid (Server + Client, no positional arg):
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+
+## SERVER OPTIONS EXPLAINED:
+--serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'memory_agent'). Runs indefinitely until Ctrl+C.
+
+--connect [ws_url]: Connects as CLIENT to remote WS server at [ws_url] (e.g., ws://127.0.0.1:8080/ws). Gains access to remote agent's tools. Interactive CLI available.
+
+--secret [string]: SHARED AUTH TOKEN (min 3 chars). SERVER rejects clients without matching --secret. CLIENTS must provide server's secret to connect. Use same secret for chains.
+
+Note: Server/Client/Hybrid IGNORES positional input arg (use CLI modes instead). Hybrid: This agent serves AND uses remote tools.
+
+## OPTIONS:
+--model [grok-4-fast-reasoning|...] (default: grok-4-fast-reasoning)
+--temperature [float] (-2 to +2)
+--tokens [number] (max output tokens)
+--top_p [float]
+--context [number] (default: 250000)
+
+## SERVER TOOLS (when no input):
+Exposes as 'memory_agent' tool for chaining.
+`);
+	process.exit();
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_name = 'memory_agent';
+const tool_call_description = `Standalone Memory Agent. Manages shared agent memory (.cache/memory.ndjson) for tasks, errors, user prefs across agents or standalone use.
+Use before/after actions: Recall relevant memories, write updates to avoid loops/repetition.
+Categories: tasks (pending work), errors (failures to avoid), prefs (user settings).
+Usable standalone, by users/agents via function calls or WebSocket connect. Responses handover to querying agent/user.`.trim();
+
+const prompt = `**CRITICAL: STRICT NO-CODING RULE** - Stick to memory coordination ONLY. NEVER use execute_bash_script/read_file/write_file for code or arbitrary files. Decline coding: "Use code_agent for code. I manage memory."
+
+You are MemoryAgent, a standalone memory manager usable by users, other agents, or as a sub-agent via function calls or WebSocket connect. Any response handovers the result to the querying agent or human user.
+
+**CORE TOOLS (local self-contained)**:
+- \`memory_recall [query]\`: Retrieve stored memories (tasks/errors/prefs). ALWAYS recall before acting (e.g., "tasks", "errors", "" for recent).
+- \`memory_write {category: "tasks|errors|prefs", content: "details"}\`: Persist info to avoid repetition/loops/token burn.
+- \`optimize_memory\`: Optimize .cache/memory.ndjson if bloated (>200 lines): Backup, prune to 100 recent unique lines (tasks/prefs priority, drop old errors), validate NDJSON. Call periodically or on heavy recalls.
+
+**SHARED STORAGE**: .cache/memory.ndjson in project CWD (all agents share).
+
+**ALWAYS**:
+1. **RECALL FIRST**: \`memory_recall "<user_query|category|''>"\` to check prior state/tasks/errors/prefs. Auto-optimize if >200 lines.
+2. **ACT**: Analyze + decide (write if new info).
+3. **WRITE IF CHANGED**: Use \`memory_write\` for decisions/tasks/errors/prefs.
+4. Respond: Summarize memories used/updated + action taken.
+
+**USER QUERIES** (handle naturally, use tools):
+- "Recall tasks" → List + suggest next.
+- "Store task: Fix auth bug" → Parse + memory_write.
+- "Clear old errors" → Recall + optimize.
+- Coordinate: "Check if code agent has pending tasks" → Recall + advise.
+
+Current date: April 03, 2026.`.trim();
+
+const agent = new AgentManager({ name, secret });
+agent.setup({
+	prompt,
+	api,
+	options,
+	toolsetMode,
+	contextWindow
+});
+const toolset = agent.getToolset();
+
+// Self-contained local memory tools (copied from genericToolset.js)
+const memoryPath = path.join(process.cwd(), '.cache', 'memory.ndjson');
+
+toolset.add(
+	'memory_recall',
+	`Retrieve stored agent memories (tasks, errors, prefs) from .cache/memory.ndjson in CWD. Use before acting to check prior decisions/tasks/errors/prefs. Query by keyword or category; empty lists recent.`,
+	{
+		type: 'object',
+		properties: {
+			query: {
+				type: 'string',
+				description: 'Keyword, category (tasks/errors/prefs), or phrase to filter (case-insensitive). Empty/omit lists last 20.'
+			}
+		},
+		required: []
+	},
+	async (params = {}) => {
+		let content;
+		try {
+			content = await fs.readFile(memoryPath, 'utf8');
+		} catch (e) {
+			return 'No memories stored yet. Use memory_write first.';
+		}
+		const lines = content.trim().split('\n').filter(l => l.trim());
+		const memories = [];
+		for (const line of lines) {
+			try {
+				memories.push(JSON.parse(line));
+			} catch {
+				// Skip invalid lines
+			}
+		}
+		if (!params.query || !params.query.toString().trim()) {
+			const recent = memories.slice(-20).reverse();
+			return recent.length
+				? 'Recent memories:\n' + recent.map(m => `• ${m.timestamp.slice(0, 19).replace('T', ' ')} [${m.category}] ${m.content}`).join('\n')
+				: 'No memories stored.';
+		}
+		const q = params.query.toString().toLowerCase();
+		const matches = memories.filter(m =>
+			m.category.toLowerCase().includes(q) || m.content.toLowerCase().includes(q)
+		);
+		return matches.length
+			? `Matches for "${params.query}":\n` + matches.slice(0, 20).map(m => `• ${m.timestamp.slice(0, 19).replace('T', ' ')} [${m.category}] ${m.content}`).join('\n')
+			: `No memories match "${params.query}".`;
+	}
+);
+
+toolset.add(
+	'memory_write',
+	`Persist agent memory for tasks, errors, or user preferences to .cache/memory.ndjson in CWD. Use to store decisions, tasks, errors, or prefs for later recall. Agent should use this to avoid repeating work or token burn on loops.`,
+	{
+		type: 'object',
+		properties: {
+			category: {
+				type: 'string',
+				enum: ['tasks', 'errors', 'prefs'],
+				description: 'Category: one of "tasks", "errors", "prefs"'
+			},
+			content: {
+				type: 'string',
+				description: 'Detailed content (e.g., "Pending task: implement runWithMemory optimization", "Error: loop burning tokens", "Pref: temperature=0.2 for decisions")'
+			}
+		},
+		required: ['category', 'content']
+	},
+	async ({ category, content }) => {
+		if (!['tasks', 'errors', 'prefs'].includes(category)) {
+			throw new Error(`Invalid category '${category}'. Must be 'tasks', 'errors', or 'prefs'.`);
+		}
+		const dir = path.dirname(memoryPath);
+		try {
+			await fs.mkdir(dir, { recursive: true });
+		} catch (e) {
+			// Dir likely exists
+		}
+		const entry = {
+			timestamp: new Date().toISOString(),
+			category,
+			content: content.trim()
+		};
+		await fs.appendFile(memoryPath, JSON.stringify(entry) + '\n', 'utf8');
+		return `✓ Memory stored: [${category}] ${content.length > 50 ? content.slice(0, 47) + '...' : content}`;
+	}
+);
+
+// optimize_memory tool
+toolset.add(
+	'memory_optimize',
+	'Optimize .cache/memory.ndjson: If >200 lines, backup, prune to last 100 unique recent lines (dedup content, prioritize tasks/prefs over old errors), compact with jq, validate NDJSON. Returns status/prune summary.',
+	{ type: 'object', properties: {} },
+	async () => {
+		let content = '';
+		try {
+			content = (await SH`cat .cache/memory.ndjson 2>/dev/null || echo ''`.run()).trim();
+		} catch (e) {
+			return 'No memory file found yet. Optimal (0 lines).';
+		}
+		const lines = content.split('\n').filter(l => l.trim()).length;
+		if (lines <= 200) {
+			return `Optimal: ${lines} lines. No action needed.`;
+		}
+		const timestamp = Date.now();
+		const backup = `.cache/memory.ndjson.bak-${timestamp}`;
+		const pruneCmd = `mkdir -p .cache && cp .cache/memory.ndjson ${backup} && tail -n 100 .cache/memory.ndjson | awk '!seen[$0]++' | jq -c . > .cache/memory.ndjson.tmp && mv .cache/memory.ndjson.tmp .cache/memory.ndjson && POST_LINES=$(wc -l < .cache/memory.ndjson | cut -d' ' -f1) && echo "Pruned ${lines}→$POST_LINES lines. Backup: ${backup}. Valid: $(cat .cache/memory.ndjson | jq empty >/dev/null 2>&1 && echo OK || echo FAIL)"`;
+		try {
+			const result = await SH`${pruneCmd}`.run();
+			return result.trim();
+		} catch (e) {
+			return `Prune failed: ${e.message}`;
+		}
+	}
+);
+
+const cliIntro = `${name} ${options.model}.
+- context: ${contextWindow}. Shared memory manager ready (self-contained local tools).
+${tool_call_name}`.trim();
+
+if (input) {
+	const RES = await agent.directCall(input);
+	console.log(RES);
+} else {
+	await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);
+}

package/{examples → agents}/npm_agent.js

@@ -55,19 +55,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "What modules are installed?" [--options]
+./agents/${name}.js "What modules are installed?" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'npm_module_inspector'). Runs indefinitely until Ctrl+C.

package/{examples → agents}/prompt_agent.js

@@ -54,19 +54,19 @@ function printHelp() {
 ## USAGE MODES:
 
 ### 1. Direct Call (One-Shot, Positional ONLY):
-./examples/${name}.js "Optimize this prompt: [prompt]" [--options]
+./agents/${name}.js "Optimize this prompt: [prompt]" [--options]
 
 ### 2. Interactive CLI (no positional arg):
-./examples/${name}.js [--options]
+./agents/${name}.js [--options]
 
 ### 3. WS Server (no positional arg):
-./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
 
 ### 4. WS Client (no positional arg):
-./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
 
 ### 5. Hybrid (Server + Client, no positional arg):
-./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
 
 ## SERVER OPTIONS EXPLAINED:
 --serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL (e.g., 'prompt_agent'). Runs indefinitely until Ctrl+C.

package/agents/spawn_agent.js

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