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

package/lib/Session.js

@@ -1,7 +1,26 @@
 /**
-* Records sessions
-* Get sessions
-* This is an optional extension for the prompt 
+* Session manager for recording and retrieving chat sessions tied to a Prompt instance.
+* Handles caching of messages, records, and logs in NDJSON files under `.cache/hello-dave/<name>/`.
+* Automatically creates session names from first non-sticky user message.
+* Listens to Prompt events (message, record, reset, truncated, others) for persistence.
+*
+* Properties:
+* - `name` (string, readonly): Sanitized prompt name used as session root folder.
+*
+* Usage:
+* ```
+* const session = new Session('my-prompt', prompt, './custom-cache');
+* console.log(session.info()); // Session details
+* const sessions = session.sessionList(); // ['user query', 'another']
+* const messages = session.set('user-query'); // Load/advance session
+* session.empty(); // Clear all data
+* ```
+*
+* @property {string} name - Sanitized prompt name (read-only).
+* @fires Prompt#message - Appends message to current session cache.
+* @fires Prompt#record - Appends record to daily records cache.
+* @fires Prompt#reset - Resets session counter/name/queue to prompt.messages.
+* @fires Prompt#truncated - Resets session like #reset.
 */
 
 import path from 'path';
@@ -14,12 +33,12 @@ import Prompt from './Prompt.js';
 */
 
 /**
- * Get the next version number for a given key in the array.
- *
- * @param {string[]} arr - The array of versioned strings.
- * @param {string} key - The key to check for the highest version.
- * @returns {number} - The next version number.
- */
+* Get the next version number for a given key in the array.
+*
+* @param {string[]} arr - The array of versioned strings.
+* @param {string} key - The key to check for the highest version.
+* @returns {number} The next version number.
+*/
 const getNextVersion = (arr, key) => {
 	const regex = new RegExp(`^${key}_(\\d+)$`);
 	const versions = arr
@@ -33,51 +52,44 @@ const getNextVersion = (arr, key) => {
 };
 
 /**
- */
+* Session class for managing persistent chat sessions with Prompt.
+*/
 class Session {
-	/**
-	* sticky message que
-	* @type {Message[]}
-	*/
-	#que = [];
-	/** @type {string} session name */
+	/** @type {Message[]} Sticky message queue. */
+	#queue = [];
+	/** @type {string} Current session name. */
 	#sessionName = '';
-	/** @type {number} count the number of session iterations */
+	/** @type {number} Current session iteration counter. */
 	#sessionCounter = 0;
-	/** @type {CacheSync} */
+	/** @type {CacheSync} Session messages cache. */
 	#sessionCache;
-	/** @type {CacheSync} */
+	/** @type {CacheSync} Records cache (billing/optimizing). */
 	#recordCache;
-	/** @type {CacheSync} */
+	/** @type {CacheSync} Logs cache (events). */
 	#logCache;
+	/** @type {string} Sanitized prompt name (public readonly). */
+	name;
 
 	/**
-	* Create and set the cache folders
+	* Initializes cache folders and event listeners.
 	* @param {string} promptName - The name of the prompt.
-	* @param {Prompt} prompt - The prompt
-	* @param {string} [baseFolder] - The base storage folder, default this is process.cwd()
+	* @param {Prompt} prompt - The Prompt instance.
+	* @param {string} [baseFolder] - Base storage folder; defaults to `.cache/hello-dave`.
+	* @private
 	*/
-	#inititializeCache = (promptName, prompt, baseFolder) => {
-		// If not base folder, we take FOLDERS.ROOT
-		// else we use the baseFolder
+	#initializeCache = (promptName, prompt, baseFolder) => {
 		if (!baseFolder) {
-			// Relative from cwd()
 			baseFolder = path.resolve('.cache', 'hello-dave');
 		}
-		// Create the root folder, just in case
 		const root = new CacheSync(baseFolder, true, 'any');
-		// this.#baseStorage = baseFolder;
 		this.name = root.sanitizeKey(promptName);
 		const sessionStorage = path.resolve(baseFolder, this.name);
-		// Create the session folder
 		new CacheSync(sessionStorage, true, 'any');
-		// Create the records cache
 		this.#logCache = new CacheSync(path.resolve(sessionStorage, 'logs'), true, 'ndjson');
 		this.#recordCache = new CacheSync(path.resolve(sessionStorage, 'records'), true, 'ndjson');
 		if (this.name.length === 0) {
 			throw new Error(`Invalid session name: ${promptName}`);
 		}
-		// create and init the session storage
 		this.#sessionCache = new CacheSync(path.resolve(sessionStorage, 'sessions'), true, 'ndjson');
 		prompt.on(prompt.EVENTS.message, (msg) => {
 			this.#msg(msg);
@@ -86,89 +98,93 @@ class Session {
 			this.#rec(rec);
 		});
 		prompt.on(prompt.EVENTS.reset, () => {
-			// Prompt has only sticky messages
-			// fill the que
 			this.#sessionCounter = 0;
 			this.#sessionName = '';
-			this.#que = prompt.messages;
+			this.#queue = prompt.messages;
 		});
 		prompt.on(prompt.EVENTS.truncated, () => {
-			// Prompt has only sticky messages
-			// fill the que
 			this.#sessionCounter = 0;
 			this.#sessionName = '';
-			this.#que = prompt.messages;
+			this.#queue = prompt.messages;
 		});
 		const events = Object.keys(prompt.EVENTS);
 		events.forEach((evt) => {
 			prompt.on(evt, (msg) => {
 				this.#log({ evt, msg });
 			});
-		})
-	}
+		});
+	};
+
 	/**
-	* Constructs a new Prompt instance.
-	* If contextWindow = 0 (defaut) the prompt will have no context building up (ONE_SHOT)
+	* Constructs a new Session instance.
+	* If contextWindow = 0 (default) the prompt will have no context building up (ONE_SHOT).
+	*
 	* @param {string} name - The name of the prompt.
-	* @param {Prompt} prompt - The prompt
-	* @param {string} [storage] - The base storage folder, default this is process.cwd()
+	* @param {Prompt} prompt - The Prompt instance.
+	* @param {string} [storage] - The base storage folder; defaults to process.cwd()/.cache/hello-dave.
 	*/
 	constructor(name, prompt, storage) {
-		this.#inititializeCache(name, prompt, storage)
+		this.#initializeCache(name, prompt, storage);
 	}
 
-  info() {
-  	const name = this.name;
-  	const session = this.#sessionName;
-  	const sessionCount = this.#sessionCounter;
-  	const path = this.#sessionCache.folder;
-  	return `Name: ${name}\nSession: ${session}\nSessionCount: ${sessionCount}\nPath: ${path}`;
-  }
 	/**
-	* Add message to the cache
-	* @param {import('./Prompt.js').Message} msg
+	* Returns current session information.
+	*
+	* @returns {string} Formatted info: Name, Session, SessionCount, Path.
+	*/
+	info() {
+		const name = this.name;
+		const session = this.#sessionName;
+		const sessionCount = this.#sessionCounter;
+		const path = this.#sessionCache.folder;
+		return `Name: ${name}\nSession: ${session}\nSessionCount: ${sessionCount}\nPath: ${path}`;
+	}
+
+	/**
+	* Appends a message to the current session cache (private).
+	* Auto-creates session name from first non-sticky user message.
+	*
+	* @param {Message} msg - The message to append.
+	* @private
 	*/
 	#msg(msg) {
 		const role = msg.role;
 		const sticky = msg.sticky;
 		let sessKey;
 		if (this.#sessionName === '' && role === 'user' && sticky === false) {
-			// Create a sessioname
 			if (msg.content.length > 0 && msg.content[0].type === 'text') {
 				/**
-				* @param {string} str
-				*/
+				 * @param {string} str
+				 */
 				const truncateString = (str) => str.length > 50 ? str.slice(0, 80) : str;
-				// @ts-ignore
 				this.#sessionName = this.#sessionCache.sanitizeKey(truncateString(msg.content[0].text).trim());
 				this.#sessionCounter = getNextVersion(this.#sessionCache.list(), this.#sessionName);
 				sessKey = this.#sessionCache.sanitizeKey(`${this.#sessionName}_${this.#sessionCounter}`);
 			}
-		} else if(this.#sessionName !== '') {
+		} else if (this.#sessionName !== '') {
 			sessKey = this.#sessionCache.sanitizeKey(`${this.#sessionName}_${this.#sessionCounter}`);
 		}
 		if (sessKey) {
-			// Alway write the que if there is a name
-			// May the must be written sticky nots or a truncated previous sessions
-			if (this.#que.length > 0) {
-				// Write outstanding messages
+			if (this.#queue.length > 0) {
 				let i = 0;
-				const len = this.#que.length;
+				const len = this.#queue.length;
 				for (; i < len; i++) {
-					this.#sessionCache.append(sessKey, this.#que[i]);
+					this.#sessionCache.append(sessKey, this.#queue[i]);
 				}
-				this.#que = [];
+				this.#queue = [];
 			}
 			this.#sessionCache.append(sessKey, msg);
 		} else {
-			this.#que.push(msg);
+			this.#queue.push(msg);
 		}
 	}
 
 	/**
-	* store a record
-	* @param {Record} record - Records for billing and optimizing
+	* Stores a record (billing/optimizing).
+	*
+	* @param {Record} record - The record to store.
 	* @throws {Error} If the record is invalid.
+	* @private
 	*/
 	#rec(record) {
 		const key = new Date().toISOString().split('T')[0];
@@ -176,21 +192,27 @@ class Session {
 	}
 
 	/**
-	* log all events
-	* @param {*} o - just log
-	* @throws {Error} If the record is invalid.
+	* Logs an event object.
+	*
+	* @param {*} o - The object to log.
+	* @throws {Error} If logging fails.
+	* @private
 	*/
 	#log(o) {
 		const key = new Date().toISOString().split('T')[0];
 		this.#logCache.append(key, o);
 	}
+
+	/**
+	* Lists unique session names (processed: remove _\d+, _ → space).
+	*
+	* @returns {string[]} Array of unique session names.
+	*/
 	sessionList() {
 		const list = this.#sessionCache.list();
 		const processedSet = new Set(
 			list.map(str => {
-				// Remove the last '_[number]' part
 				const withoutNumber = str.replace(/_\d+$/, '');
-				// Replace '_' with ' '
 				return withoutNumber.replace(/_/g, ' ');
 			})
 		);
@@ -198,10 +220,11 @@ class Session {
 	}
 
 	/**
-	* Get messages fro, a session
-	* 
+	* Sets/advances to a session and loads its messages.
+	* Updates counter to last version if exists.
+	*
 	* @param {string} sess - The session name.
-	* @return {Message[]}
+	* @returns {Message[]} Messages from the session (or []).
 	*/
 	set(sess) {
 		const counter = getNextVersion(this.#sessionCache.list(), sess);
@@ -210,7 +233,6 @@ class Session {
 		} else {
 			this.#sessionCounter = counter - 1;
 		}
-		// Load last know session
 		const sessKey = this.#sessionCache.sanitizeKey(`${sess}_${this.#sessionCounter}`);
 		const res = this.#sessionCache.read(sessKey) || [];
 
@@ -219,8 +241,9 @@ class Session {
 		}
 		return res;
 	}
+
 	/**
-	* Remove all previous sessions and records
+	* Empties all caches: sessions, records, logs.
 	*/
 	empty() {
 		this.#sessionCache.empty();

package/lib/ToolSet.js

@@ -1,30 +1,30 @@
 import Prompt from "./Prompt.js";
 /**
-* @module @j-o-r/toolset
-* Register function_calls / tools
-* This library can be used stand-alone or as a wrapper for AI functions_calls tools
-*/
+ * @module @j-o-r/toolset
+ * Register function_calls / tools
+ * This library can be used stand-alone or as a wrapper for AI functions_calls tools
+ */
 
 /**
-* @typedef {object} TSSchema
-* @property {string} type - Type of the object
-* @property {object} properties - Description of properties
-* @property {string[]} [required] - Required properties
-*/
+ * @typedef {object} TSSchema
+ * @property {string} type - Type of the object
+ * @property {object} properties - Description of properties
+ * @property {string[]} [required] - Required properties
+ */
 /**
-* @typedef {object} TSTool
-* @property {string} description - Command description
-* @property {TSSchema} parameters - JS JSON schema
-* @property {function(object): Promise} method
-*/
+ * @typedef {object} TSTool
+ * @property {string} description - Command description
+ * @property {TSSchema} parameters - JS JSON schema
+ * @property {function(object): Promise<*>} method - The async method to execute
+ */
 /**
-* @typedef {object} TSToolListItem
-* @property {string} name - Command name
-* @property {string} description - Command description
-* @property {TSSchema} parameters - JS JSON schema
-*/
+ * @typedef {object} TSToolListItem
+ * @property {string} name - Command name
+ * @property {string} description - Command description
+ * @property {TSSchema} parameters - JS JSON schema
+ */
 
-/** Type of choices */
+/** @enum {string} Type of choices for tool usage */
 const CHOICES = {
 	NONE: 'none',
 	AUTO: 'auto',
@@ -32,21 +32,27 @@ const CHOICES = {
 };
 
 /**
-* The function name is limited
-* @param {string} s
-* @returns {boolean}
-*/
+ * Validates if the given string is a valid tool name.
+ * Valid names match the regex /^[#!a-z_0-9]{2,}$/
+ * @param {string} s - The string to validate
+ * @returns {boolean} True if valid, false otherwise
+ */
 const isValidName = (s) => /^[#!a-z_0-9]{2,}$/.test(s);
 
+/**
+ * @classdesc ToolSet manages a collection of tools (functions) that can be registered and executed, typically for AI agent function calling.
+ * Supports schema definition compatible with JSON Schema for parameters.
+ */
 class ToolSet {
-	/** @type {Map<string, TSTool>} */
+	/** @type {Map<string, TSTool>} Private map storing registered tools */
 	#tools = new Map();
-	/** default auto */
+	/** @private Default tool choice setting */
 	#toolChoice = 'auto';
 
 	/**
-	* @param {string} [choice] - Default 'auto' auto|none|required
-	*/
+	 * Constructs a new ToolSet instance.
+	 * @param {string} [choice='auto'] - Default tool choice: 'auto' | 'none' | 'required'
+	 */
 	constructor(choice = 'auto') {
 		if (choice && Object.values(CHOICES).includes(choice)) {
 			this.#toolChoice = choice;
@@ -56,20 +62,21 @@ class ToolSet {
 	}
 
 	/**
-	* How many functions have we registered
-	* @returns {number}
-	*/
+	 * Getter for the number of registered tools.
+	 * @returns {number} The count of tools in the set
+	 */
 	get length() {
 		return this.#tools.size;
 	}
 
 	/**
-	* Register a Tool/Command/Function
-	* @param {string} name - [a-z_0-9]{2,} The lowercase string name of the callback e.g. 'get_node_version'
-	* @param {string} description - What does it do
-	* @param {TSSchema} parameters - SCHEMA object describing the function's input parameters
-	* @param {function(object): Promise<*>} method - Async function to call
-	*/
+	 * Registers a new tool/command/function in the set.
+	 * Overwrites if already exists (no error thrown).
+	 * @param {string} name - The lowercase string name of the tool e.g. 'get_node_version'. Must match /^[#!a-z_0-9]{2,}$/
+	 * @param {string} description - Human-readable description of what the tool does
+	 * @param {TSSchema} parameters - JSON Schema object describing the input parameters
+	 * @param {function(object): Promise<*>} method - The async function to call with parsed parameters
+	 */
 	add(name, description, parameters, method) {
 		if (typeof name !== 'string') {
 			throw new Error('Tool name must be a string');
@@ -78,42 +85,45 @@ class ToolSet {
 			throw new Error(`Invalid tool name '${name}': must match /^[#!a-z_0-9]{2,}$/`);
 		}
 		if (this.has(name)) {
-			// throw new Error('Function already defined');
+			// Note: Allows overwrite without error
 		}
 		this.#tools.set(name, { description, parameters, method });
 	}
 
 	/**
-	* Get a  tool from the toolset
-	* @param {string} name
-	* @returns {TSTool}
-	*/
+	 * Retrieves a registered tool by name.
+	 * @param {string} name - The name of the tool
+	 * @returns {TSTool} The tool object
+	 * @throws {Error} If tool not found
+	 */
 	get(name) {
 		if (!this.has(name)) {
 			throw new Error('Function not found');
 		}
 		return this.#tools.get(name);
 	}
+
 	/**
-	* Delete a function_call
-	* @param {string} name
-	*/
+	 * Deletes a tool from the set by name.
+	 * @param {string} name - The name of the tool to delete
+	 */
 	delete(name) {
 		this.#tools.delete(name);
 	}
+
 	/**
-	* Is 'name' already registered
-	* @param {string} name
-	* @returns {boolean}
-	*/
+	 * Checks if a tool with the given name is registered.
+	 * @param {string} name - The tool name to check
+	 * @returns {boolean} True if the tool exists
+	 */
 	has(name) {
 		return this.#tools.has(name);
 	}
 
 	/**
-	* Get a list of tools available
-	* @returns {TSToolListItem[]}
-	*/
+	 * Returns a sorted list of all registered tools (excluding methods).
+	 * @returns {TSToolListItem[]} Array of tool summaries, sorted by name
+	 */
 	list() {
 		return Array.from(this.#tools.entries()).map(([name, value]) => ({
 			name,
@@ -122,15 +132,21 @@ class ToolSet {
 		})).sort((a, b) => a.name.localeCompare(b.name));
 	}
 
+	/**
+	 * Getter for the current tool choice setting.
+	 * @returns {string} The tool choice: 'auto', 'none', or 'required'
+	 */
 	get toolChoice() {
 		return this.#toolChoice;
 	}
+
 	/**
-	* Execute a method
-	* @param {string} name
-	* @param {object} params
-	* @returns {Promise<*>}
-	*/
+	 * Executes a specific tool by name with given parameters.
+	 * @param {string} name - The tool name
+	 * @param {object} params - The parameters object
+	 * @returns {Promise<*>} The result from the tool method
+	 * @throws {Error} If tool not found or execution fails
+	 */
 	async call(name, params) {
 		if (!this.has(name)) {
 			throw new Error('Function not found');
@@ -138,9 +154,12 @@ class ToolSet {
 		const tool = this.#tools.get(name);
 		return tool.method(params);
 	}
+
 	/**
-	 * Execute function requests from the last message.
-	 * @param {Prompt} prompt - Handle tool calls.
+	 * Processes and executes function requests from the last message in a Prompt.
+	 * Automatically handles multiple calls, emits events, and adds responses back to the prompt.
+	 * @param {Prompt} prompt - The Prompt instance containing the last message with function_request(s)
+	 * @returns {Promise<void>}
 	 */
 	async execute(prompt) {
 		const lastMessage = prompt.getLastMessage();
@@ -187,4 +206,4 @@ class ToolSet {
 	}
 }
 
-export default ToolSet;
+export default ToolSet;

package/lib/fafs.js

@@ -10,27 +10,55 @@ new CacheAsync(RELATIVE_CACHE, true, 'bin');
 const APP_CACHE = path.resolve(RELATIVE_CACHE, APPNAME);
 new CacheAsync(APP_CACHE, true, 'bin');
 
+/**
+ * Frequently Asked Functions (FAFS) - Utility module providing environment and system information utilities.
+ * 
+ * Main features:
+ * - `env()`: Gathers user, system, location, and path info (cached 31 days).
+ * - `systemInfo()`: Detailed OS/architecture/working dir string.
+ * - `GLOBAL`: Shared config (max requests, cache path, secret).
+ * 
+ * @module fafs
+ * @exports {function} env
+ * @exports {function} systemInfo
+ * @exports {Object} GLOBAL
+ * @exports {function} jsType
+ */
+
+/**
+ * @typedef {Object} EnvironmentInfo
+ * @property {string} name - User's full name (from passwd GECOS field)
+ * @property {string} system - System information (OS release, architecture, kernel, cwd)
+ * @property {string} city - City from external IP geolocation
+ * @property {string} region - Region/State from IP
+ * @property {string} country - Country from IP
+ * @property {string} timezone - Timezone from IP
+ * @property {string} external_ip - External IP address
+ * @property {string} cwd - Current working directory (relative to home as ~)
+ */
+
+/**
+ * Global configuration and constants for the application.
+ * @type {Object}
+ * @property {number} max_recursive_requests - Maximum number of recursive requests allowed (default: 20)
+ * @property {string} default_cache - Path to the default application cache directory
+ * @property {string} secret - Secret key for cache encryption/security
+ */
 const GLOBAL = {
-	max_recursive_requests: 20, // max number recursive of request 
+	max_recursive_requests: 20,
 	default_cache: APP_CACHE,
 	secret: 'tdb.e3a0cd73dd6a429283f921f9fc1bad41'
 }
 
 /**
-* @typedef {Object} EnvironmentInfo
-* @property {string} name - User's name
-* @property {string} system - Linux OS / PROC 
-* @property {string} city
-* @property {string} region
-* @property {string} country
-* @property {string} timezone
-* @property {string} external_ip
-* @property {string} cwd - current working folder
-*/
-
-/**
-* @returns {Promise<string>}
-*/
+ * Retrieves detailed system information including OS release (/etc/issue), machine architecture (uname -m),
+ * operating system (uname -o), and current working directory.
+ * 
+ * @returns {Promise<string>} Formatted multi-line string with system details.
+ * @example
+ * const info = await systemInfo();
+ * // "system: Ubuntu 25.10 \n\nx86_64\nGNU/Linux\ncwd: /home/user/project"
+ */
 async function systemInfo() {
 	let system = 'system: ' +  (await SH`cat /etc/issue`.run()).trim().replace('\\n', '').replace('\\l', '');
 	system += (await SH`uname -m`.run()).trim().replace('\\n', '').replace('\\l', '');
@@ -48,9 +76,15 @@ async function systemInfo() {
 }
 
 /**
-* Gather information about this environment
-* @returns {Promise<EnvironmentInfo>}
-*/
+ * Gathers comprehensive environment information: user name, fresh system details, IP-based geolocation,
+ * and normalized current working directory. Results are cached in ~/.cache/hello-dave/env for 31 days,
+ * refreshed on expiry. On cache hit, updates with fresh system info and cwd.
+ * 
+ * @returns {Promise<EnvironmentInfo>} The environment information object.
+ * @example
+ * const envInfo = await env();
+ * console.log(envInfo.name, envInfo.city, envInfo.system);
+ */
 async function env() {
   const CACHE_PATH = (await SH`echo ~/.cache/${APPNAME}`.run()).trim();
 	const KEY = 'env';
@@ -82,6 +116,7 @@ async function env() {
 		timezone: userInfo.timezone,
 		external_ip: userInfo.ip
 	}
+	info.cwd = cwd;
 	await storage.write(KEY, JSON.stringify(info));
 	return info;
 }
@@ -91,4 +126,4 @@ export {
 	GLOBAL,
 	env,
 	systemInfo
-}
+}