@j-o-r/hello-dave 0.0.2 → 0.0.4

package/examples/readme_agent.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs, readIn } from '@j-o-r/sh';
+
+const name = 'readme_agent';
+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;
+
+/** @type {import('lib/API/x.ai/responses.js').XAIOptions} */
+const options = { tools : []};
+options.tools.push({
+	type: 'web_search'
+});
+if (args['secret']) { // model gets default value
+	secret = args['secret'];
+}
+// Set properties only if provided via command line (except model which has default)
+if (args['model'] || true) { // model gets default value
+	// @ts-ignore
+	options.model = args['model'] || 'grok-4-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 = args['reasoning'] ? args['reasoning'] : null;
+if (reasoning) {
+	options.reasoning = {
+		// @ts-ignore
+		effort: reasoning,
+		summary: 'auto'
+	}
+}
+
+const toolsetMode = 'auto';
+const contextWindow = args['context'] ? parseInt(args['context']) : 250000;
+
+// Copy from the generic toolset
+function printHelp() {
+	console.log(`
+'${name} --help' You are looking at it.
+
+OPTIONS: 
+--tokens [number]: max generated tokens 
+--context [number] : truncate message history to context-windows size default 130000
+--temperature [float] : -2 / +2
+--model [grok-4|grok-3|grok-3-mini|grok-3-mini-fast|grok-code-fast-1]
+--top_p [float]: number > 0, 0.1 means no top_p
+--reasoning [low|high]
+--tools [javascript,bash] comma seperated list
+
+SERVER TOOLS:
+--serve [number]: create a Agent server on port number ws://127.0.0.1:[serve]/ws
+--connect [url]: connect to a Server Agent e.g ws://127.0.0.1:8080/ws (https://my.domain/ws) ...
+--secret [string] : limit access to websocket server with a secret
+`);
+	process.exit()
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_description = `
+Project README manager. Maintains README.md with comprehensive project documentation.
+Inspects current README.md, updates sections (installation, usage, etc.), generates content based on project files and user input.
+Suggests improvements, adds badges, TOC, etc.
+`.trim();
+const tool_call_name = 'readme_agent';
+const prompt = `
+You are an expert README.md manager for this project. README.md should follow best practices with sections like:
+
+# Project Title
+![Badges]
+
+## Table of Contents
+
+## Description
+## Features
+## Installation
+## Usage
+## Examples
+## Development
+## Contributing
+## License
+
+**CRITICAL: STRICT NO-CODING RULE** - Stick to README management ONLY. NEVER:
+- Use coding tools (e.g., javascript_interpreter, read_file, write_file, syntax_check, npm_module_inspector).
+- Generate, execute, or edit code (JS/Python/Bash beyond safe README ops).
+- Misuse bash for anything beyond safe README.md ops (e.g., cat README.md, echo > README.md, cp README.md README.md.bak, ls, git status).
+If asked to code or edit non-README files, decline: "For coding or other tasks, use specialized agents like code_agent. I'll handle README.md only."
+
+ALWAYS:
+
+1. Inspect the current README.md if it exists (use \`cat README.md\` or similar).
+
+2. Inspect key project files safely: \`cat package.json\`, \`ls -la\`, \`ls bin/\`, \`ls lib/\`, \`git status\`, etc.
+
+3. Understand the user input: 
+   - "add installation instructions"
+   - "generate usage examples"
+   - "add table of contents"
+   - "update description to: ..."
+   - "suggest improvements"
+   - "include npm badges"
+   - "make it more professional"
+
+4. Update README.md with changes. Ensure excellent Markdown formatting, accuracy based on project. Backup first if overwriting: \`cp README.md README.md.bak\`.
+
+5. Write the FULL updated content to ./README.md using safe bash (e.g., echo "content" > README.md).
+
+6. In your response, summarize:
+   - Changes made
+   - Preview of key sections (e.g., first 20 lines)
+   - Any suggestions for further enhancements
+
+If no README.md exists, create a comprehensive one by analyzing the entire project: package.json, code structure, scripts, etc. Infer project name, description, usage from files.
+
+Use execute_bash_script ONLY for safe README ops and inspections. Use web_search for best practices if needed.
+`.trim();
+const agent = new AgentManager({ name, secret });
+agent.setup({
+	prompt,
+	api,
+	options,
+	toolsetMode,
+	contextWindow
+});
+const toolset = agent.getToolset();
+if (toolset) {
+	agent.addGenericToolcall('execute_bash_script');
+}
+const cliIntro = `
+${name} ${options.model}.
+- context: ${contextWindow}
+`.trim();
+
+await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);

package/examples/spawn_agent.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+
+const name = 'spawn_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):
+./examples/${name}.js "Create a code agent" [--options]
+
+### 2. Interactive CLI (no positional arg):
+./examples/${name}.js [--options]
+
+### 3. WS Server (no positional arg):
+./examples/${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]
+
+### 5. Hybrid (Server + Client, no positional arg):
+./examples/${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., 'spawn_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 'spawn_agent' tool for chaining.
+`);
+	process.exit()
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_name = 'spawn_agent';
+const tool_call_description = `
+Portable creator for CLI/WS agents (bin/<name>.js) + PM2 multi-agent launchers. Validates/tests/deploys. No local docs needed.
+`.trim();
+
+const REPO_URL = 'https://codeberg.org/duin/hello-dave';
+const DOCS_BASE = `${REPO_URL}/src/branch/main/docs/`;
+const EXAMPLES_URL = `${REPO_URL}/src/branch/main/examples/`;
+
+const promptParts = [
+  'You are AgentCreator, expert in @j-o-r/hello-dave. Create production-ready CLI agents (bin/<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/examples).',
+  '',
+  '**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 bin examples`.',
+  '3. `cat package.json` (project name). `ls -la bin/`.',
+  '',
+  '**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 ./bin/${name}.js FULL_CODE`, `chmod +x ./bin/${name}.js`.',
+  '6. **TEST**: `execute_bash_script \'./bin/${name}.js "Briefly describe yourself and your modes (CLI/server/client)"\'` → Show output.',
+  '7. **SERVER/CLIENT GUIDE**: "Test server: ./bin/${name}.js --serve 8081 (find free port). Client: echo \'query\' | ./bin/${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 examples/<Name>Server (e.g., examples/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:
+  ./bin/AGENTNAME             # Interactive CLI
+  echo "query" | ./bin/AGENTNAME  # One-shot
+  ./bin/AGENTNAME --serve 8081    # WS Server
+  ./bin/AGENTNAME --connect ws://host:8081/ws --secret KEY  # WS Client
+  ./bin/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}/bin/mainagent.js" --name "\${FOLDER}_mainagent_\${PORT}" -- --serve "\${PORT}" --tools javascript --secret "\${SECRET}"
+# Subs as clients
+pm2 start "\${SCRIPT_DIR}/bin/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/examples/CodeServer'
+];
+
+const prompt = promptParts.join('\\n');
+
+const agent = new AgentManager({ name, secret });
+agent.setup({
+	prompt,
+	api,
+	options,
+	toolsetMode,
+	contextWindow
+});
+const toolset = agent.getToolset();
+if (toolset) {
+	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 Agent Creator: Builds CLI/WS agents + CodeServer launchers **anywhere** (auto-deps, online docs).
+
+Examples: 
+- "Create code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file execute_bash_script web_search"
+- "Generate CodeServer launcher for coderev + tododave + npmdave"`.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/test_agent.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+
+const name = 'test_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):
+./examples/${name}.js "Generate test for toolset.js" [--options]
+
+### 2. Interactive CLI (no positional arg):
+./examples/${name}.js [--options]
+
+### 3. WS Server (no positional arg):
+./examples/${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]
+
+### 5. Hybrid (Server + Client, no positional arg):
+./examples/${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., 'test_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 'test_agent' tool for chaining.
+`);
+	process.exit()
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_name = 'test_agent';
+const tool_call_description = `
+TestDave: Generates executable tests (Test class) for project files/utils/agents in ./scenarios/*.test.js.
+Uses memories, delegates to code/npm/etc. agents.
+`.trim();
+
+const prompt = `You are TestAgent, the specialized testing agent for CodeServer projects. Your sole responsibility is to create, manage, and execute tests using the lightweight 'Test' class from '@j-o-r/sh' (already installed).
+
+**CORE MISSION**:
+- Write executable test scripts in ./scenarios/ folder with the extension *.test.js (e.g., scenarios/toolset.test.js).
+- Tests must use: \`import { Test, assert, jsType } from '@j-o-r/sh';\`
+- Structure: shebang \`#!/usr/bin/env node\`, fluent Test API (\`const t = new Test(); t.add('desc', () => { assert... }); await t.run();\`), exit(1) on errors.
+- After write_file to scenarios/MODULE.test.js, ensure executable: \`chmod +x scenarios/MODULE.test.js\`
+- Leverage project utilities: test existing files (examples/*.js, toolset.js, agents, SH commands, etc.) using read_file, execute_bash_script (ls/cat), npm_module_inspector.
+
+**WHAT TO TEST** (discover dynamically):
+1. Project scripts: e.g., parseArgs, AgentManager flows, toolsets.
+2. Utilities: SH commands, async hooks, promise tracking.
+3. Agents: code_agent, npm_agent, memory_agent integrations.
+4. Existing: genericToolset.test.js patterns, sh.js, etc.
+- Query: "Write test for toolset.js" → read_file toolset.js → generate scenarios/toolset.test.js.
+
+**Test Example** (from @j-o-r/sh docs):
+\`\`\`
+#!/usr/bin/env node
+import { Test, assert, jsType } from '@j-o-r/sh';
+
+const t = new Test();
+t.add('Basic assert', () => assert.strictEqual(1 + 1, 2));
+t.add('Type check', () => assert.strictEqual(jsType([]), 'Array'));
+t.add('Async test', async () => {
+  const p = Promise.resolve('ok');
+  assert.strictEqual(await p, 'ok');
+});
+const report = await t.run();
+process.exit(report.errors > 0 ? 1 : 0);
+\`\`\`
+
+**WORKFLOW** (per user request, e.g., "test parseArgs"):
+1. Recall memories (tasks/errors for testing).
+2. Inspect target: read_file, execute_bash_script \`ls lib/\`, npm_module_inspector.
+3. Generate test: Plan tests (coverage: happy path, errors, async), write to scenarios/{target}.test.js (e.g., scenarios/parseArgs.test.js).
+4. Validate: execute_bash_script \`node scenarios/{target}.test.js\` or \`./scenarios/{target}.test.js\`.
+5. Report results, store outcomes.
+
+**MANDATORY MEMORY PROTOCOL** (ALWAYS FIRST/LAST):
+1. RECALL: memory_agent "Recall relevant memories: tasks, errors, prefs for [test target, e.g., toolset.js]."
+2. CORE: Write/Run tests in scenarios/*.test.js.
+3. WRITE: memory_agent "Store updates: Task: [next test], Error: [test fail], Pref: [coverage style]."
+
+**PRIORITIES**:
+- Safety: CWD-only, validate syntax before write (write_file auto-checks).
+- Coverage: assertions (strictEqual, ok, throws), types (jsType), async (promises).
+- Executable: shebang + chmod +x scenarios/*.test.js.
+- Reuse: Import project utils (e.g., import {parseArgs} from './toolset.js').
+- Current date: April 01, 2026.
+
+FOLLOW RIGIDLY: Memory first/last, scenarios/*.test.js only, Test class exclusively.
+`.trim();
+
+const agent = new AgentManager({ name, secret });
+agent.setup({
+	prompt,
+	api,
+	options,
+	toolsetMode,
+	contextWindow
+});
+const toolset = agent.getToolset();
+if (toolset) {
+	agent.addGenericToolcall('history_search');
+	agent.addGenericToolcall('memory_recall');
+	agent.addGenericToolcall('memory_write');
+	agent.addGenericToolcall('javascript_interpreter');
+	agent.addGenericToolcall('execute_bash_script');
+	agent.addGenericToolcall('read_file');
+	agent.addGenericToolcall('write_file');
+}
+const cliIntro = `
+${name} ${options.model}.
+- context: ${contextWindow}.
+${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);
+}