@j-o-r/hello-dave 0.0.6 → 0.0.8

package/lib/genericToolset.js

@@ -14,46 +14,56 @@ const listSessionsSh = path.join(utilsDir, 'list_sessions.sh');
 const syntaxCheckSh = path.join(utilsDir, 'syntax_check.sh');
 
 const user = await env();
-const environment = ` 
+const environment = `
 Name: ${user.name}
 System: ${user.system}
 City: ${user.city}
 Region: ${user.region}
 Country: ${user.country}
 Timezone: ${user.timezone}
-ExternalIp: ${user.external_ip}  
+ExternalIp: ${user.external_ip}
 `.trim();
 const tools = new ToolSet('auto');
 
 /**
-* reduce the error output to essential info only, if possible
-* @param {string} errorStr
-* @returns {string}
-*/
+ * Reduces verbose JavaScript evaluation error output to essential info (line number + core message).
+ * @param {string} errorStr - Full Node.js error string.
+ * @returns {string} Simplified error.
+ * @private
+ */
 const getJSError = (errorStr) => {
 	let result = '';
 	const linematch = errorStr.match(/\[eval\]:(\d+)/);
 	const lineNumber = linematch ? linematch[1] : '';
 	const match = errorStr.split(/\" \"\[eval\]:\d+/s);
 	if (match.length > 1) {
-		// Remove last 10 lines
 		const res = match[1].split('\n').slice(0, -10).join('\n');
-		result = `Error: line ${lineNumber}\n${res} `
+		result = `Error: line ${lineNumber}\n${res} `;
 	} else {
 		result = errorStr;
 	}
 	return result;
-}
+};
 
+/**
+ * @module lib/genericToolset
+ * Secure utility tools for code execution, file I/O, system ops. Pre-populated ToolSet.
+ * 
+ * @example
+ * import tools from './lib/genericToolset.js';
+ * await tools.call('get_user_env', {});
+ * 
+ * @see {@link module:./index~ToolSet}
+ */
 tools.add(
 	'javascript_interpreter',
-	`Execute ESM ES6 javascript on \`node\`.`,
+	'Execute ESM ES6 JavaScript on node.',
 	{
 		type: 'object',
 		properties: {
 			script: {
 				type: 'string',
-				description: `ES6 ESM Javascript eval. 'console.log' to capture the response. cwd: ${user.cwd}`,
+				description: `ES6 ESM code. Use console.log for output. cwd: ${user.cwd}`
 			}
 		},
 		required: ['script']
@@ -67,53 +77,60 @@ ${params.script}
 ${delim}
 `.run();
 		} catch (e) {
-			const errorStr = e.toString();
-			response = getJSError(errorStr);
+			response = getJSError(e.toString());
 		}
 		return response;
 	}
 );
+
 tools.add(
-	'get_user_env', // name
-	'Get the user location, name and OS environment', // desciption
-	{
-		type: 'object',
-		properties: {
-		}
-	},
-	async (_params) => {
-		return environment;
-	}
+	'get_user_env',
+	'Get user environment info.',
+	{ type: 'object', properties: {} },
+	async () => environment
 );
 
 tools.add(
 	'execute_bash_script',
-	'Execute a bash script or command. (char escaping not needed)',
+	'Execute raw bash script or command (no escaping needed). Supports timeout to prevent hangs.',
 	{
 		type: 'object',
 		properties: {
-			bash_script: { type: 'string', description: `RAW bash script (LITERAL TEXT: NO ESCAPING—output $, |, <, >, &, ", ', \\, \` , newlines, $(()), [[ ]] verbatim. Heredoc delimiter handles safely. EX: echo "$((1+1)) | grep \'<&>\"hi$USER\"\' && ls -la\`. (${user.system})` }
+			bash_script: {
+				type: 'string',
+				description: `Raw bash verbatim. Supports all syntax safely via stdin. System: ${user.system}`
+			},
+			timeout: {
+				type: 'number',
+				default: 360,
+				description: 'Max execution time in seconds (default 360 seconds, 0 is no timeout). Uses @j-o-r/sh timeout (ms) with SIGTERM on expiry to prevent hangs from interactive prompts or slow commands.'
+			}
 		},
 		required: ['bash_script']
 	},
 	async (params) => {
-		const delim = `END_SCRIPT_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+		const timeoutSec = Number(params.timeout ?? 300);
+		if (isNaN(timeoutSec) || timeoutSec < 0) throw new Error('Invalid timeout');
+		const timeout = timeoutSec * 1000;
+		// return await SH`bash`.options({ timeout: timeoutMs }).run(params.bash_script);
+    const delim = `END_SCRIPT_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 		return await SH`bash <<'${delim}'
 ${params.bash_script}
 ${delim}
-`.run()
+`.options({timeout}).run();
+
 	}
 );
 
 tools.add(
 	'send_email',
-	'Send an email.',
+	'Send email via msmtp.',
 	{
 		type: 'object',
 		properties: {
-			to: { type: 'string', description: 'Recipient email' },
+			to: { type: 'string', description: 'Recipient' },
 			subject: { type: 'string', description: 'Subject' },
-			body: { type: 'string', description: 'Message body' }
+			body: { type: 'string', description: 'Body' }
 		},
 		required: ['to', 'subject', 'body']
 	},
@@ -128,193 +145,169 @@ ${delim}
 `.run();
 	}
 );
+
 tools.add(
 	'open_link',
-	'Open an url or file in the local user environment. (xdg-open)',
+	'Open URL/file with xdg-open.',
 	{
 		type: 'object',
 		properties: {
-			url: { type: 'string', description: 'file | URL' }
+			url: { type: 'string', description: 'URL or file path' }
 		},
 		required: ['url']
 	},
-	async (params) => {
-		return await SH`xdg-open ${[params.url]}`.run();
-	}
+	async (params) => await SH`xdg-open ${[params.url]}`.run()
 );
+
 tools.add(
 	'execute_remote_script',
-	'Execute bash script on a remote machine via SSH.',
+	'Run bash on remote via SSH. Supports timeout to prevent hangs.',
 	{
 		type: 'object',
 		properties: {
-			url: { type: 'string', description: 'SSH URL, e.g., ssh://user@host or ssh://user@host:port' },
-			script: { type: 'string', description: 'RAW script code to execute remotely (no escaping needed)' }
+			url: { type: 'string', description: 'ssh://user@host[:port]' },
+			script: { type: 'string', description: 'Raw script' },
+			timeout: {
+				type: 'number',
+				default: 30,
+				description: 'Max execution time in seconds (default 30). Uses @j-o-r/sh timeout (ms) with SIGTERM on SSH process expiry.'
+			}
 		},
 		required: ['url', 'script']
 	},
 	async (params) => {
 		const { url, script } = params;
-		if (!url.startsWith('ssh://')) throw new Error('Invalid SSH URL');
+		const timeoutSec = Number(params.timeout ?? 30);
+		if (isNaN(timeoutSec) || timeoutSec <= 0) throw new Error('Invalid timeout');
+		const timeoutMs = timeoutSec * 1000;
+		if (!url.startsWith('ssh://')) throw new Error('ssh://user@host[:port]');
 		const withoutProto = url.slice(6);
 		const parts = withoutProto.split(':');
-		let port = 22;
-		let userHost = withoutProto;
-		if (parts.length > 1) {
-			userHost = parts[0];
-			port = parseInt(parts[1]);
-		}
+		let port = 22, userHost = withoutProto;
+		if (parts.length > 1) { userHost = parts[0]; port = parseInt(parts[1]); }
 		const [user, host] = userHost.split('@');
-		if (!user || !host) throw new Error('Invalid SSH URL format: use ssh://user@host[:port]');
-
-		const delim = `END_SCRIPT_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-		return await SH`ssh -p ${port} ${user}@${host} bash <<'${delim}'
-${script}
-${delim}
-`.run();
-
+		if (!user || !host) throw new Error('Invalid SSH URL');
+		return await SH`ssh -p ${port} ${user}@${host} bash`.options({ timeout: timeoutMs }).run(script);
 	}
 );
+
 tools.add(
 	'history_search',
-	`Search previous LLM chat sessions or list them hierarchically.
-Example query: "(todo|task)" or "package.json".
-Searches filenames & content in .cache/[app]/[prompt]/sessions/*.ndjson (case-insensitive regex, with context).
-Omit query (or use empty string) to list sessions (see utils/list_sessions.sh).`,
+	'Search/list chat sessions in .cache/.',
 	{
 		type: 'object',
 		properties: {
-			query: {
-				type: 'string',
-				description: `Search query or regex (quoted for multi-word/regex). Omit or empty for list mode.`
-			}
+			query: { type: 'string', description: 'Query/regex or empty to list' }
 		},
 		required: []
 	},
 	async (params) => {
-		if (typeof params.query === 'string' && params.query.trim() !== '') {
-			const escapedQuery = bashEscape(params.query);
-			return await SH`${searchSessionsSh} "${escapedQuery}"`.run();
-		} else {
-			return await SH`${listSessionsSh}`.run();
+		if (typeof params.query === 'string' && params.query.trim()) {
+			return await SH`${searchSessionsSh} "${bashEscape(params.query)}"`.run();
 		}
+		return await SH`${listSessionsSh}`.run();
 	}
 );
+
 tools.add(
 	'read_file',
-	'Read the raw content of a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..).',
+	'Read file from CWD (relative path only).',
 	{
 		type: 'object',
 		properties: {
-			file: {
-				type: 'string',
-				description: `Relative path to the file within CWD, e.g., 'path/to/file.txt' (no escaping needed). cwd: ${user.cwd}`
-			}
+			file: { type: 'string', description: `Relative path. cwd: ${user.cwd}` }
 		},
 		required: ['file']
 	},
 	async (params) => {
 		const file = params.file?.trim();
-		if (typeof file !== 'string' || !file) {
-			throw new Error('Valid relative file path required.');
-		}
-		if (file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
-			throw new Error('Path must be relative within CWD only (no `/`, `..`, or `\\\\`).');
-		}
-		const resolvedPath = path.resolve(process.cwd(), file);
-		if (!resolvedPath.startsWith(process.cwd())) {
-			throw new Error(`Path '${file}' escapes CWD scope.`);
-		}
-		try {
-			const content = await fs.readFile(resolvedPath, 'utf8');
-			return content;
-		} catch (e) {
-			throw new Error(`Failed to read '${file}': ${e.message}`);
+		if (typeof file !== 'string' || !file || file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
+			throw new Error('Relative CWD path only (no /, .., \\\\).');
 		}
+		const resolved = path.resolve(process.cwd(), file);
+		if (!resolved.startsWith(process.cwd())) throw new Error('Escapes CWD.');
+		return await fs.readFile(resolved, 'utf8');
 	}
 );
 
 tools.add(
 	'write_file',
-	'**MANDATORY**: 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 in params**). **AUTO-VALIDATES** JS/Python/Bash/JSON/etc. via `utils/syntax_check.sh`; chmod +x shebangs. Retries syntax errors force LLM fix. **Always use write_file for safety (CWD-only, syntax-checked).**',
+	'Write/validate file in CWD. Auto-syntax check + JS fix + chmod.',
 	{
 		type: 'object',
 		properties: {
-			file: {
-				type: 'string',
-				description: `Relative path to the file within CWD, e.g., 'path/to/file.txt' (no escaping needed). cwd: ${user.cwd}`
-			},
-			content: {
-				type: 'string',
-				description: "Raw content to write (LITERAL: NO char escaping needed in this param; supports newlines, $, |, <, >, &, \", ', \\, \` , etc. verbatim). **Generate valid syntax for target lang** (e.g., JS template literals use raw `${var}`, no invalid \\`; syntax_check.sh rejects bad syntax like escaped backticks in JS)."
-			}
+			file: { type: 'string', description: `Relative path. cwd: ${user.cwd}` },
+			content: { type: 'string', description: 'Raw content verbatim (no escaping).' }
 		},
 		required: ['file', 'content']
 	},
 	async (params) => {
 		const file = params.file?.trim();
 		const content = params.content ?? '';
-		if (typeof file !== 'string' || !file) {
-			throw new Error('Valid relative file path required.');
+		if (typeof file !== 'string' || !file || file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
+			throw new Error('Relative CWD path only.');
 		}
-		if (file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
-			throw new Error('Path must be relative within CWD only (no `/`, `..`, or `\\\\`).');
-		}
-		const resolvedPath = path.resolve(process.cwd(), file);
-		if (!resolvedPath.startsWith(process.cwd())) {
-			throw new Error(`Path '${file}' escapes CWD scope.`);
-		}
-		try {
-			await fs.writeFile(resolvedPath, content, 'utf8');
+		const resolved = path.resolve(process.cwd(), file);
+		if (!resolved.startsWith(process.cwd())) throw new Error('Escapes CWD.');
+		const dir = path.dirname(resolved);
+		const ext = path.extname(file);
+		let finalContent = content, validationMsg = '';
 
-			// AUTO-VALIDATE: Multi-lang syntax check via utils/syntax_check.sh + chmod shebang
-			const hasShebang = content.startsWith('#!');
+		const temp1 = path.join(dir, `temp_${Date.now()}_${Math.random().toString(36).slice(2,6)}${ext || '.tmp'}`);
+		await fs.writeFile(temp1, content, 'utf8');
 
-			let validationMsg = '';
-			try {
-				await SH`${syntaxCheckSh} ${[resolvedPath]}`.run();
-				validationMsg = ' ✓ Multi-lang syntax OK';
-			} catch (e) {
-				const errPreview = content.slice(0, 1000).split('\n').slice(0, 20).join('\n');
-				throw new Error(`❌ SYNTAX ERROR in '${file}' (syntax_check.sh failed):\n${e.message}\n\nPREVIEW:\n${errPreview}\n\n... Fix syntax (quotes/backticks) and retry write_file.`);
+		try {
+			await SH`${syntaxCheckSh} ${[temp1]}`.run();
+			validationMsg = ' ✓ Syntax OK';
+		} catch (e) {
+			if (!['.js','.mjs'].includes(ext)) {
+				await fs.unlink(temp1).catch(()=>{}); 
+				throw new Error(`Syntax error: ${e.message}`);
 			}
-			if (hasShebang) {
-				await SH`chmod +x ${[resolvedPath]}`.run();
-				validationMsg += ' ✓ chmod +x';
+			let fixed = content.replace(/\\\\`/g, '\\`').replace(/\\\`/g, '`').replace(/\\`/g, '`').replace(/\\\$/g, '$').replace(/\\\${/g, '${');
+			const temp2 = path.join(dir, `temp_fix_${Date.now()}_${Math.random().toString(36).slice(2,6)}.js`);
+			await fs.writeFile(temp2, fixed, 'utf8');
+			try {
+				await SH`${syntaxCheckSh} ${[temp2]}`.run();
+				finalContent = fixed;
+				await fs.rename(temp2, resolved);
+				await fs.unlink(temp1).catch(()=>{}); 
+				validationMsg = ' ✓ Fixed JS';
+			} catch {
+				await fs.unlink(temp1).catch(()=>{}); 
+				await fs.unlink(temp2).catch(()=>{}); 
+				throw new Error(`Syntax error (fix failed): ${e.message}`);
 			}
+		}
 
-			return `Successfully wrote to '${file}' (${Buffer.byteLength(content, 'utf8')} bytes).${validationMsg}`;
-		} catch (e) {
-			throw new Error(`Failed to write '${file}': ${e.message}`);
+		if (validationMsg === ' ✓ Syntax OK') await fs.rename(temp1, resolved);
+
+		if (finalContent.startsWith('#!')) {
+			await SH`chmod +x ${[resolved]}`.run();
+			validationMsg += ' ✓ +x';
 		}
+
+		return `Wrote ${file} (${Buffer.byteLength(finalContent, 'utf8')} bytes).${validationMsg}`;
 	}
 );
 
 tools.add(
 	'syntax_check',
-	'Standalone syntax validation for files (JS/Python/Bash/JSON/etc.) via utils/syntax_check.sh. Detects lang from ext/shebang.',
+	'Syntax validate file via utils/syntax_check.sh.',
 	{
 		type: 'object',
 		properties: {
-			file: {
-				type: 'string',
-				description: `Relative path to the file within CWD.`
-			}
+			file: { type: 'string', description: 'Relative CWD path' }
 		},
 		required: ['file']
 	},
 	async (params) => {
 		const file = params.file?.trim();
-		if (typeof file !== 'string' || !file) {
-			throw new Error('Valid relative file path required.');
-		}
-		const resolvedPath = path.resolve(process.cwd(), file);
-		if (!resolvedPath.startsWith(process.cwd())) {
-			throw new Error(`Path '${file}' escapes CWD scope.`);
-		}
-		return await SH`${syntaxCheckSh} ${[resolvedPath]}`.run();
+		if (typeof file !== 'string' || !file) throw new Error('Relative path required.');
+		const resolved = path.resolve(process.cwd(), file);
+		if (!resolved.startsWith(process.cwd())) throw new Error('Escapes CWD.');
+		return await SH`${syntaxCheckSh} ${[resolved]}`.run();
 	}
 );
 
-
-export default tools
+export default tools;

package/lib/wsCli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env -S node
-/*
- * WebSocket client for a hello-dave server with auto-reconnect and improved structure.
- * user CLI 
+/**
+ * @fileoverview Interactive WebSocket CLI client for hello-dave agent servers.
+ * Features: auto-reconnect, keyboard shortcuts (ALT-C/R/I/S/M, CTRL-K), 
+ * session management, message history, clipboard copy.
+ * 
+ * Depends on @j-o-r/cli for terminal UI, @j-o-r/apiserver WebSocketClient, @j-o-r/sh for shell.
  */
 import cli from '@j-o-r/cli';
 import { WebSocketClient } from "@j-o-r/apiserver";
@@ -9,11 +12,17 @@ import { SH } from '@j-o-r/sh';
 
 const OPEN = 1; // WebSocket.OPEN
 
+/**
+ * @typedef {Object} WsMessage
+ * @property {string} action - Action type (e.g., 'user_request')
+ * @property {string} content - Message content
+ * @property {number} id - Unique message ID
+ */
 
 /**
  * Copy text to the clipboard using xclip.
- * @param {string} text
- * @returns {Promise<void>}
+ * @param {string} text - Text to copy
+ * @returns {Promise&lt;void&gt;}
  */
 const copyToClipboard = async (text) => {
 	if (typeof text !== 'string') return;
@@ -21,11 +30,28 @@ const copyToClipboard = async (text) => {
 	const prams = ['-selection', 'clipboard'];
 	await SH`xclip ${prams}`.options({ stdio: 'inherit' }).run(text);
 };
+
 /**
-* Launch a CLI to an Agent Server
-* @param {string} connectUrl - Websocket server endpoint to connect to
-* @param {string} [secret] - Secret websocket connection key
-*/
+ * Launches an interactive CLI client connected to a hello-dave agent server via WebSocket.
+ * Establishes persistent connection with auto-reconnect, handles user input,
+ * keyboard shortcuts for common actions, and displays responses.
+ * 
+ * Keyboard shortcuts:
+ * - ALT-C: Clear screen
+ * - ALT-R: Reset session
+ * - ALT-S: List/load sessions
+ * - ALT-I: Server info
+ * - ALT-M: Copy last message to clipboard
+ * - CTRL-K: Show help
+ * - CTRL-D: Exit (standard)
+ * 
+ * @param {string} connectUrl - WebSocket server endpoint (e.g., 'ws://localhost:8080')
+ * @param {string} [secret=''] - Optional base64 secret for authenticated connections
+ * @returns {void}
+ * @example
+ * import wsCli from './lib/wsCli.js';
+ * wsCli('ws://localhost:8080', 'mysecret');
+ */
 export default (connectUrl, secret = '') => {
 	let ws;
 	let busy = false;
@@ -36,8 +62,12 @@ export default (connectUrl, secret = '') => {
 	}
 
 	/**
-	 * Connect to the WebSocket server (with handlers).
-	 * Sets up reconnection on close.
+	 * Connects (or reconnects) to the WebSocket server.
+	 * Sets up event handlers for messages, close (auto-reconnect), errors.
+	 * Sends user_introduction on open.
+	 * 
+	 * @private
+	 * @returns {void}
 	 */
 	const connect = () => {
 		if (ws && ws.readyState === OPEN) {
@@ -94,10 +124,14 @@ export default (connectUrl, secret = '') => {
 	};
 
 	/**
-	 * Send a message and await response.
-	 * Handles response actions and UI updates.
-	 * @param {Object} message - Message object (action, content)
-	 * @returns {Promise<Object>} Response data
+	 * Sends a message and awaits response by ID.
+	 * Handles special response actions (e.g., server_response updates UI).
+	 * Manages busy state and spinner.
+	 * 
+	 * @private
+	 * @param {WsMessage} message - Message to send (id auto-added)
+	 * @returns {Promise&lt;WsMessage&gt;} Response data
+	 * @throws {Error} If not connected, timeout (12h), or connection error
 	 */
 	const sendMessage = async (message) => {
 		if (!ws || ws.readyState !== OPEN) {
@@ -246,11 +280,8 @@ Available keys:
 	};
 
 	// Initialize
-
 	cli.focus('log');
 	cli.write('Connecting... (ALT-I for info, CTRL-K for keys, CTRL-D to exit)');
 
 	connect();
-
-}
-
+};

package/lib/wsIO.js

@@ -14,17 +14,21 @@ import { WebSocket } from 'ws';
 * Sends intro + action, awaits matching response by ID, closes, returns response.
 * 
 * @param {string} connectUrl - Websocket server endpoint to connect to
-* @param {string} [secret] - Secret websocket connection key
-* @param {'user_request'|'user_info'|'user_reset'} action - Action
-* @param {string} [input] - When action is  'user_request' input is the query
-* @returns {Promise<wsResponse>}
+* @param {string} [secret=''] - Secret websocket connection key
+* @param {'user_request'|'user_info'|'user_reset'} action - Action to perform
+* @param {string} [input=''] - Input content (required for 'user_request')
+* @returns {Promise&lt;wsResponse&gt;}
+* @throws {Error} Invalid action or missing input for user_request
+* @example
+* const response = await wsio('ws://localhost:8080', 'secret', 'user_request', 'Hello!');
+* console.log(response.content);
 */
 export default async function wsio(connectUrl, secret = '', action, input = '') {
 	if (!['user_request', 'user_reset', 'user_info'].includes(action)) {
-		throw new Error(`Invalid action: ${action}. Must be one of: user_input, user_reset, user_info`);
+		throw new Error(`Invalid action: ${action}. Must be one of: user_request, user_reset, user_info`);
 	}
 	if (action === 'user_request' && (!input || typeof input !== 'string' || input.trim() === '')) {
-		throw new Error('Non-empty string input required for "user_input"');
+		throw new Error('Non-empty string input required for "user_request"');
 	}
 
 	let b64secret = '';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@j-o-r/hello-dave",
   "type": "module",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "ESM toolkit for building AI agents with unified access to Grok (XAI), OpenAI, and Anthropic endpoints",
   "main": "./lib/index.js",
   "types": "./types/index.d.ts",
@@ -14,7 +14,7 @@
   },
   "bin": {
     "dave": "bin/dave.js",
-    "createAgent": "bin/spawn_agent.js"
+    "codeDave": "bin/codeDave"
   },
   "scripts": {
     "release": "npm run types && npm pack --pack-destination=release",
@@ -51,4 +51,4 @@
   "engines": {
     "node": ">=20"
   }
-}
+}