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

package/lib/Cli.js

@@ -1,38 +1,42 @@
 import cli from '@j-o-r/cli';
 import { SH } from '@j-o-r/sh';
 // import audio2text from './tts/openai.com/generate.js';
+
 /**
-* @typedef {import('./API/openai.com/reponses/text.js').request} OARequest
-* @typedef {import('./API/x.ai/text.js').request} XRequest
-* @typedef {import('./API/anthropic.com/text.js').request} ANTHRequest
-* 
-* @typedef {import('./API/x.ai/text.js').XOptions} XOptions
-* @typedef {import('./API/openai.com/reponses/text.js').OAOptions} OAOptions
-* @typedef {import('./API/anthropic.com/text.js').ANTHOptions} ANTHOptions
-*
-* @typedef {import('./Prompt.js').default} Prompt
-* @typedef {import('./Session.js').default} Session
-* @typedef {import('./ToolSet.js').default} ToolSet
-*/
+ * @typedef {import('./API/openai.com/reponses/text.js').request} OARequest
+ * @typedef {import('./API/x.ai/text.js').request} XRequest
+ * @typedef {import('./API/anthropic.com/text.js').request} ANTHRequest
+ * 
+ * @typedef {import('./API/x.ai/text.js').XOptions} XOptions
+ * @typedef {import('./API/openai.com/reponses/text.js').OAOptions} OAOptions
+ * @typedef {import('./API/anthropic.com/text.js').ANTHOptions} ANTHOptions
+ *
+ * @typedef {import('./Prompt.js').default} Prompt
+ * @typedef {import('./Session.js').default} Session
+ * @typedef {import('./ToolSet.js').default} ToolSet
+ */
 /**
+ * Configuration options for initializing the Cli class.
  * @typedef {Object} CLIOptions
- * @property {Prompt} prompt - The prompt session
- * @property {Session} session - Session  Cache
- * @property {ToolSet} [toolset] - The toolset
- * @property {string} [description] - Custom introduction message.
- * @property {string} [help] - Custom help message.
+ * @property {Prompt} prompt - The Prompt instance for handling AI interactions.
+ * @property {Session} session - The Session instance for managing conversation history.
+ * @property {ToolSet} [toolset] - Optional ToolSet for tool integrations.
+ * @property {string} [description] - Custom introduction message (appended to default INTRO).
+ * @property {string} [help] - Custom help message (overrides default HELP).
  */
 
-
+/** @const {string} Short introduction with basic shortcuts. */
 const INTRO = `
 Use:
   - "ALT + d" to exit.
   - "ALT + k" Show shortcuts /help
 `;
 
+/** @const {string} Error message template (customizable via options.help). */
 const ERROR = `
-`
+`;
 
+/** @const {string} Full help text with shortcuts and prompt commands. */
 const HELP = `
 
 Use:
@@ -57,23 +61,24 @@ e.g. >edit< , >paste< , >#!bash [command]<
 `;
 
 /**
-* Copy text to the clipboard
-* @param {string} text
-* @retruns {Promise<string>}
-*/
-const copyToClipboard = async (text) => {
-	if (typeof text !== 'string') return;
-	if (text === '') text = ' ';
-	const prams = [
-		'-selection',
-		'clipboard'
-	]
-	return SH`xclip ${prams}`.options({ stdio: 'inherit' }).run(text);
-}
-
-
-/**
- * CLILoader class for handling CLI-based interactions with AI models.
+ * CLI Interface for interactive AI conversations.
+ * 
+ * Integrates with {@link Prompt}, {@link Session}, and optionally {@link ToolSet} to provide a terminal-based chat interface.
+ * Supports keyboard shortcuts (Alt + key), session management, error handling, and real-time message streaming.
+ * 
+ * Key features:
+ * - Rich text output with roles (user/assistant/util/error/log).
+ * - Event-driven updates from Prompt (messages, truncated, finished).
+ * - Built-in help, reset, load session, copy last message (Alt+m).
+ * - Customizable intro/help via options.
+ * 
+ * @example
+ * const cli = new Cli({ prompt: myPrompt, session: mySession });
+ * await cli.start('Hello, AI!');
+ * 
+ * @fires Prompt#message
+ * @fires Prompt#truncated
+ * @fires Prompt#finished
  */
 class Cli {
 	#HELP = HELP;
@@ -84,22 +89,30 @@ class Cli {
 	#prompt;
 	#description = '';
 	#lastMessage = '';
+
 	/**
-	 * Creates an instance of CLILoader.
-	 * @param {CLIOptions} options - The options to configure the CLILoader.
+	 * Initializes the Cli instance with required Prompt and Session.
+	 * Sets up CLI roles, key mappings, and event listeners on Prompt.
+	 * @param {CLIOptions} options - Configuration options.
+	 * @throws {Error} If required prompt or session is missing.
 	 */
 	constructor(options) {
+		if (!options.prompt || !options.session) {
+			throw new Error('Cli requires valid prompt and session options.');
+		}
 		this.#prompt = options.prompt;
 		this.#session = options.session;
-		this.#description = (options.description) ? options.description + INTRO : INTRO;
-		this.#HELP = (options.help) ? options.help : HELP;
+		this.#description = options.description ? options.description + '\n\n' + INTRO : INTRO;
+		this.#HELP = options.help || HELP;
 		this.#setupCLI();
 	}
 
-	#setupCLI = () => {
+	/** @private */
+	#setupCLI() {
 		cli.setRole('assistant', `${this.#session.name}: > `, 'brightGreen');
 		cli.setRole('util', ``, 'brightYellow');
 		cli.setRole('error', ``, 'red');
+		cli.setRole('log', '', 'brightBlue');
 		// @ts-ignore
 		cli.inputHandler = async (s, role) => await this.#handleInput(s, role);
 		cli.registerKeyMappings([
@@ -109,34 +122,31 @@ class Cli {
 					await this.reset();
 				}
 			},
-			{ // load a previous ssession
+			{ // load a previous session
 				name: 's', ctrl: false, meta: true, shift: false, handler: async () => {
 					await this.loadSession();
 				}
 			},
-			{ // load a previous ssession
+			{ // show session/prompt info
 				name: 'i', ctrl: false, meta: true, shift: false, handler: async () => {
 					this.printInfo();
-					// cli.focus('user', true);
 				}
 			},
 			{ // Copy last message to clipboard
 				name: 'm', ctrl: false, meta: true, shift: false, handler: async () => {
 					await copyToClipboard(this.#lastMessage);
 					cli.focus('util');
-					cli.write('copied');
-					// cli.focus('user', true);
+					cli.write('Last message copied to clipboard.');
 				}
 			},
 			{ // Show help /keys
 				name: 'k', ctrl: false, meta: true, shift: false, handler: async () => {
-					cli.focus('util')
-					cli.write(HELP)
-					// cli.focus('user', true);
+					cli.focus('util');
+					cli.write(this.#HELP);
 				}
 			}
 		]);
-		// Write messages
+		// Event listeners for Prompt updates
 		this.#prompt.on('message', (msg) => {
 			let write = false;
 			if (msg.role === 'reasoning') {
@@ -150,7 +160,7 @@ class Cli {
 				cli.write(content);
 				write = true;
 			} else if (msg.role === 'assistant') {
-				if (msg.content[0].type === 'text') {
+				if (msg.content[0]?.type === 'text') {
 					const content = this.#prompt.contentToString(msg.content);
 					if (content.trim() !== '') {
 						cli.focus('assistant');
@@ -160,63 +170,67 @@ class Cli {
 				}
 			}
 			if (write) {
-			  cli.startSpinner();
+				cli.startSpinner();
 			}
 		});
 		this.#prompt.on('truncated', () => {
 			cli.focus('log');
-			cli.write(`--- prompt truncated ---`);
-			// cli.startSpinner();
+			cli.write('--- prompt truncated ---');
 		});
 		this.#prompt.on('finished', () => {
 			cli.focus('user', true);
 		});
-		// console.log(this.#prompt);
 	}
 
 	/**
-	 * @param {string} s
-	 * @param {string} role
+	 * Handles user input, processes via Prompt.call(), captures last message, and manages errors.
+	 * Only processes 'user' role inputs.
+	 * @private
+	 * @param {string} s - Input string.
+	 * @param {string} role - Input role (e.g., 'user').
 	 */
 	async #handleInput(s, role) {
-		if (!s || s === '') {
-			return;
-		}
-		// Only accept a users input 
-		if (role === 'user') {
-			cli.startSpinner();
-			try {
-				this.#lastMessage = await this.#prompt.call(s)
-			} catch (error) {
-				// @ts-ignore
-				await this.#handleError(error);
-			}
+		if (!s || s.trim() === '') return;
+		if (role !== 'user') return;
+		cli.startSpinner();
+		try {
+			this.#lastMessage = await this.#prompt.call(s);
+		} catch (error) {
+			await this.#handleError(error);
 		}
 	}
 
 	/**
-	 * @param {Error} error
+	 * Displays error message and focuses back to user input.
+	 * @private
+	 * @param {Error} error - The error to handle.
 	 */
 	async #handleError(error) {
-		cli.error(error);
+		cli.error(error.message || error);
 		cli.focus('util');
-		cli.write(this.#ERROR);
-		// this.reset();
+		cli.write(this.#ERROR || 'An error occurred. Try Alt+r to reset.');
 		cli.focus('user', true);
 	}
 
-  printInfo() {
+	/**
+	 * Prints detailed info about current session and prompt, plus description.
+	 * Triggered by Alt+i.
+	 */
+	printInfo() {
 		const sessionInfo = this.#session.info();
 		const promptInfo = this.#prompt.info();
-		const info = `\nSESSION\n${sessionInfo}\nPROMPT\n${promptInfo}\n${this.#description}`;
+		const info = `\nSESSION\n${sessionInfo}\n\nPROMPT\n${promptInfo}\n\n${this.#description}`;
 		cli.focus('util');
 		cli.write(info);
-  }
+	}
 
 	/**
-	 * Starts the CLI interaction.
-	 * @param {string} [s] - optional user string/question
+	 * Starts the CLI: Shows intro/description, focuses user input, optionally processes initial message.
+	 * @param {string} [s] - Optional initial user message to process.
 	 * @returns {Promise<void>}
+	 * @example
+	 * await cli.start(); // Interactive mode
+	 * await cli.start('What is the weather?'); // Start with query
 	 */
 	async start(s) {
 		cli.focus('util');
@@ -226,11 +240,17 @@ class Cli {
 			await this.#handleInput(s, 'user');
 		}
 	}
+
+	/**
+	 * Loads a previous session by user selection, replays non-sticky messages, and triggers request.
+	 * Lists sessions in reverse chronological order + 'NONE'.
+	 * Triggered by Alt+s.
+	 * @returns {Promise<void>}
+	 */
 	async loadSession() {
-		// Last session last
-		const sess = this.#session.sessionList().reverse();
-		sess.push('NONE');
-		const selected = await cli.select('Select your session: ', sess);
+		const sessions = this.#session.sessionList().reverse();
+		sessions.push('NONE');
+		const selected = await cli.select('Select session: ', sessions);
 		if (!selected || selected === 'NONE') {
 			cli.focus('user', true);
 			return;
@@ -239,25 +259,38 @@ class Cli {
 		const messages = this.#session.set(selected);
 		this.#prompt.messages = messages;
 		messages.forEach((msg) => {
-			if (!msg.sticky) {
-				if (['user', 'assistant', 'reasoning', 'log'].includes(msg.role)) {
-					const content = this.#prompt.contentToString(msg.content);
-					// @ts-ignore
-					cli.focus(msg.role);
-					cli.write(content);
-				}
+			if (!msg.sticky && ['user', 'assistant', 'reasoning', 'log'].includes(msg.role)) {
+				const content = this.#prompt.contentToString(msg.content);
+				cli.focus(msg.role);
+				cli.write(content);
 			}
 		});
 		cli.startSpinner();
 		await this.#prompt.triggerRequest();
-		// cli.focus('user', true);
 	}
+
+	/**
+	 * Resets the prompt (clears context), reprints info, triggered by Alt+r.
+	 * @returns {Promise<void>}
+	 */
 	async reset() {
-		this.#prompt.reset();
-		// this.start();
+		await this.#prompt.reset();
 		this.printInfo();
-		// cli.focus('user', true);
+		cli.focus('user', true);
 	}
 }
 
+/**
+ * Copies text to the system clipboard using xclip.
+ * @param {string} text - Text to copy (non-empty string).
+ * @returns {Promise<void>}
+ * @throws {Error} If xclip fails or invalid input.
+ */
+const copyToClipboard = async (text) => {
+	if (typeof text !== 'string' || text === '') return;
+	const params = ['-selection', 'clipboard'];
+	await SH`xclip ${params}`.options({ stdio: 'inherit' }).run(text);
+};
+
 export default Cli;
+export { copyToClipboard };

package/lib/Prompt.js

@@ -290,13 +290,46 @@ const isValidFunctionResponse = (msg) => {
 	}
 	return false
 }
+
 /**
-* 
-* @fires Prompt#add
-* Event: message added
+* Manages a conversation history of standardized AI messages (text, image, audio, tool calls/responses)
+* across different LLM providers (OpenAI, xAI, Anthropic). Inspired by OpenAI's chat format but extended.
+*
+* Key features:
+* - Message validation and ordering (roles: system, user, assistant, tool, reasoning, log)
+* - Context window management with automatic truncation (preserves sticky base prompts)
+* - ToolSet integration via adapters for function calls
+* - Token counting, records for billing/optimization
+* - Event-driven lifecycle (e.g., 'message', 'start', 'finished', tool events)
+*
+* Typical usage:
+*   const prompt = new Prompt(4096);
+*   prompt.setAdaptor(openaiHandler, toolset, options);
+*   prompt.add('system', 'You are helpful.', true);
+*   const response = await prompt.call('Hello!');
+*
+* @extends {EventEmitter}
+* @property {number} contextLength - Maximum token limit (getter)
+* @property {Message[]} messages - Copy of conversation history (getter/setter)
+* @property {ToolSet|null} toolset - Current toolset (getter)
+* @property {boolean} hasSystemprompt - Whether system prompt exists (getter)
+* @property {string} system_prompt - System prompt text (getter)
 *
-* @event Prompt#add
-* @type {Message}
+* @fires Prompt#start - Emitted when a request starts
+* @fires Prompt#retrigger - Retrigger after message import
+* @fires Prompt#finished - Request completed
+* @fires Prompt#message - New message added to history
+* @fires Prompt#record - Token usage record added
+* @fires Prompt#truncated - Messages truncated due to context limit
+* @fires Prompt#reset - Non-sticky messages cleared
+* @fires Prompt#ready - Call/trigger ready
+* @fires Prompt#error - Error occurred
+* @fires Prompt#warning - Warning issued (e.g., token overflow)
+* @fires Prompt#tool_request - Tool call initiated
+* @fires Prompt#tool_response - Tool call completed
+* @fires Prompt#tool_error - Tool call failed
+* @fires Prompt#http_request - HTTP tool request starts
+* @fires Prompt#http_response - HTTP tool response received
 */
 class Prompt extends EventEmitter {
 	#tokenCount = 0;