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

package/examples/npm_agent.js.bak.4

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+
+const name = 'npm_agent';
+const api = 'xai';
+let secret = '';
+
+let input; // Directcall input
+const args = parseArgs();
+
+if (args._.length === 1 && typeof args._[0] === 'string' && args._[0].trim() !== '') {
+	input = args._[0].trim();
+} else {
+	// Fallback for piped stdin (async readIn)
+	const { readIn } = await import('@j-o-r/sh');
+	input = await readIn();
+}
+
+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):
+./examples/${name}.js "What modules are installed?" [--options]
+
+### 2. Pipe/Stdin (One-Shot):
+echo "What modules are installed?" | ./examples/${name}.js [--options]
+
+### 3. Interactive CLI:
+./examples/${name}.js [--options]
+
+### 4. WS Server (no input):
+./examples/${name}.js --serve 8080 [--secret mysecret] [--options]
+
+### 5. WS Client (no input):
+./examples/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
+
+### 6. Hybrid (Server + Client):
+./examples/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
+
+## 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)
+--secret [string] (WS auth)
+
+## SERVER TOOLS (when no input):
+Exposes as 'npm_module_inspector' tool for chaining.
+`);
+	process.exit()
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_name = 'npm_module_inspector';
+const tool_call_description = `
+NPM modules expert (scoped & unscoped). Uses \`npm ls -a\` + bash **exclusively inside ./node_modules/**.
+**Smart Cache**: .cache/npm-agent-storage.md (auto-read/update, token-efficient, auto-refreshes on changes). Agent-owned.
+`.trim();
+
+const CACHE_FILE = '.cache/npm-agent-storage.md';
+
+const prompt = `
+You are a coding assistant specializing in Bash and JavaScript (ESM/ESNext), with support for other languages.
+Your role: Help users code with external NPM modules installed in the project's ./node_modules/ (dynamic CWD).
+Scoped (@j-o-r/cli) == unscoped (gpt-3-encoder) priority.
+
+CWD dynamic (pwd; project root w/ package.json/node_modules).
+
+CRITICAL: **NEVER** inspect/read **OUTSIDE** ./node_modules/. NO project files. **ONLY** \`npm ls -a\` (local) + node_modules/ paths. **NEVER** run \`npm install\` or suggest installs unless NO existing/native alternative (justify HEAVILY, prefer polyfills).
+
+**Dependency Strategy**: For all coding requests, follow this order to keep dependencies minimal (prevent bloat):
+1. **Always try existing installed modules first**: Scan \`npm ls -a\` FULL TREE (all subdeps). Prioritize functions from ANY module.
+2. **Native code**: Node.js/Bash builtins ONLY if no module match.
+3. **Suggest new dep LAST/RARE**: ABSOLUTELY NO unless gap proven (no existing/native). Heavy justification + \`npm i --save-dev PKG\` (dev pref). Goal: ZERO new installs.
+
+**Auto-Cache Init (MANDATORY FIRST on EVERY query - FULL SCAN)**:
+touch ${CACHE_FILE}
+echo "## Full Tree (npm ls -a unique modules)" >> ${CACHE_FILE}
+npm ls -a --parseable 2>/dev/null | sed 's|.*/||' | sort -u | head -50 >> ${CACHE_FILE}  # All unique PKGs (top + sub)
+echo "## Top-Level (--depth=0)" >> ${CACHE_FILE}
+npm ls --depth=0 | grep -E '^[├└]──' | sed 's/^[├└ ]*── //' | sed 's/ .*//' >> ${CACHE_FILE}
+**Condensed Scan**: find node_modules/ -name package.json | sed 's|.*/||;s|/package.json||' | sort -u > ${CACHE_FILE}.allmods
+
+**Vague Query Mode** (e.g., "tests"): 
+- Full scan: \`npm ls -a | grep -i "\$QUERY" || find node_modules/ -name "*.d.ts" -o -name "*.js" | head -50 | xargs grep -lE "\$QUERY|test|assert" | sed 's|.*/||;s|\..*||' | sort -u\`
+- Output table: Module | Exports | For | Usage (from all tree).
+- Append "## QUERY: \$QUERY\nHits: list" >> ${CACHE_FILE}
+
+**Smart Cache (.cache/npm-agent-storage.md)**: Agent-owned, **auto-managed FULL TREE** (read-first, update-on-change).
+- Token Saver: Grep FIRST across all sections.
+- Init: touch .cache/npm-agent-storage.md
+
+PRIORITIZE \`npm ls -a\` (full tree) + bash inside ALL MODULE_DIRs.
+
+Tools:
+- execute_bash_script: \`npm ls -a ...\` + \`cat node_modules/\$PKG_NAME/package.json\`. Prefix ALWAYS.
+- web_search: Docs ONLY.
+- history_search: Chats.
+
+**Smart Workflow** (per query; full tree always):
+1. **Full Tree Installed/Version**:
+   PKGS=\$(npm ls -a --parseable 2>/dev/null | sed 's|.*/||' | sort -u | head -50)
+   for PKG in \$PKGS; do npm ls "\$PKG" 2>/dev/null | tail -1 | grep -o 'v[0-9].*' || echo "\$PKG ??"; done
+
+2. **Smart Cache Check**:
+   grep -A 30 "^## Full Tree" .cache/npm-agent-storage.md || echo "Cache miss"
+
+3. **Inspect if Miss** (loop top 10 hits):
+   - For each MODULE_DIR=node_modules/\$PKG: [existing inspect + enhanced types/docs grep]
+   - Vague: grep -riE "\$QUERY" node_modules/\$PKG/*.{json,md,d.ts,js} | head -20
+
+4. **Auto-Update Cache** (CONDENSED, FULL):
+   sed -i.bak "/^## Full Tree/,/^## QUERY/d" ${CACHE_FILE} && rm ${CACHE_FILE}.bak
+   cat >> ${CACHE_FILE} << EOC
+## Full Tree (npm ls -a)
+\$ALL_PKGS (50 unique)
+
+## \$PKG v\$VER
+Exports: \$EXPORTS
+For: \$KEYWORDS (test/query hits)
+Usage: import {fn} from '\$PKG';
+EOC
+
+5. **List All**: \`npm ls -a | head -50 | grep -E '^[├└]' | sed 's/^[├└ ]*── //' | cut -d@ -f1 | sort -u\`
+
+6. **Coding Help**: ESM/Bash snippets from FULL TREE. **MANDATORY**: Strategy + table + "NO new deps - use existing \$PKG".
+
+**MANDATORY**: FULL \`npm ls -a\` every time. Vague scans ALL modules. **STRICT NO INSTALLS** unless proven gap. Condensed output. Portable.
+`.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('javascript_interpreter');
+	agent.addGenericToolcall('execute_bash_script');
+	agent.addGenericToolcall('read_file');
+	agent.addGenericToolcall('write_file');
+}
+const cliIntro = `
+${name} ${options.model}.
+- context: ${contextWindow}. Smart cache: ${CACHE_FILE} (FULL npm ls -a auto).
+${tool_call_name}
+`.trim();
+
+if (!input || input.trim() === '') {
+	printHelp();
+}
+
+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/npm_agent.js.bak.5

@@ -0,0 +1 @@
+Full backup before CLI no-args fix

package/examples/npm_agent.js.bak.6

@@ -0,0 +1 @@
+# Backup before adding serve/connect/secret explanations to printHelp

package/examples/prompt_agent.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+
+const name = 'prompt_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 "Optimize this prompt: [prompt]" [--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., 'prompt_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 'prompt_agent' tool for chaining.
+`);
+	process.exit();
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_name = 'prompt_agent';
+const tool_call_description = `Prompt optimizer. Analyzes prompts for clarity, brevity, ethics, token efficiency. Approves good ones or rewrites with summary/questions.`.trim();
+
+const prompt = `**CRITICAL: STRICT NO-CODING RULE** - Stick to prompt optimization ONLY. NEVER:
+- Use execute_bash_script, javascript_interpreter, write_file, read_file, syntax_check.
+- Generate, execute, or edit code.
+If asked to code, decline: "For code tasks, use code_agent.js. I optimize prompts only."
+
+You are a prompt optimizer. Check for: 1) Clarity and specificity. 2) Brevity, non-ambiguity, ethics. 3) Token efficiency. If good, say "Approved." If not, rewrite concisely or ask 1-2 questions. Output: - Summary. - Rewritten prompt (if needed). - Questions (if unclear). Be efficient.
+
+Current date: April 01, 2026.`.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('open_link');
+	agent.addGenericToolcall('send_email');
+	// Removed execute_bash_script and javascript_interpreter for NO-CODING compliance
+}
+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);
+}

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);