@j-o-r/hello-dave 0.1.0 → 0.1.4

package/lib/API/x.ai/text.js

@@ -1,415 +0,0 @@
-/**
-* [api documentation](https://docs.x.ai/docs/overview)
-*/
-import { GLOBAL } from '../../fafs.js'
-import { request as doRequest } from '@j-o-r/apiserver';
-import { sleep } from '@j-o-r/sh';
-/**
-* @typedef {import('../../Prompt.js').default} Prompt
-* @typedef {import('../../ToolSet.js').default} ToolSet
-*/
-/**
-* @typedef {"grok-4"|"grok-3"|"grok-3-mini"|"grok-3-fast"|"grok-3-mini-fast"} grokModels
-* @typedef {"low"|"high"} grokReason
-*/
-/**
-* @typedef {Object} SearchParameters
-* @property {"on"|"auto"} mode
-* @property {string}  [from_date]  ISO-8601 date (YYYY-MM-DD)
-* @property {string}  [to_date]    ISO-8601 date (YYYY-MM-DD)
-* @property {(RssSource|WebSource|NewsSource|XSource)[]} [sources]
-*
-* @typedef {Object} RssSource
-* @property {"rss"} type
-* @property {string[]} links
-*
-* @typedef {Object} WebSource
-* @property {"web"} type
-* @property {string}  [country]            ISO-3166-1 alpha-2
-* @property {boolean} [safe_search=true]
-* @property {string[]} [allowed_websites]  // cannot coexist with excluded_websites
-* @property {string[]} [excluded_websites]
-*
-* @typedef {Object} NewsSource
-* @property {"news"} type
-* @property {string}  [country]
-* @property {boolean} [safe_search=true]
-* @property {string[]} [allowed_websites]
-* @property {string[]} [excluded_websites]
-*
-* @typedef {Object} XSource
-* @property {"x"} type
-*/
-/**
-* @typedef {object} XRequest
-* @property {XOptions} body
-* @property {Headers} headers
-* @property {string} url - 
-*/
-/**
-* @typedef {Object} XFunctionCall
-* @property {string} name - The name of the function to call.
-* @property {string} arguments - The arguments for the function call in JSON string format.
-* @typedef {Object} XToolCall
-* @property {string} id - The unique identifier for the tool call.
-* @property {string} type - The type of the tool call, e.g., "function".
-* @property {XFunctionCall} function - The function call details.
-*/
-/**
-* @typedef {Object} XFunctionResponse
-* @property {string} role - must be 'tool' 
-* @property {string} content - The arguments for the function call in JSON string format.
-* @property {string} tool_call_id - The unique identifier for the tool call.
-*/
-/**
-* @typedef {Object} XMessageResponse
-* @property {number} index - The index of the message.
-* @property {Object} message - The message details.
-* @property {string} message.role - The role of the sender (e.g., "assistant").
-* @property {string} message.content - The content of the message.
-* @property {string} [message.reasoning_content] - The reasoning behind the response.
-* @property {?string} message.refusal - Any refusal content, if applicable.
-* @property {string} finish_reason - The reason for finishing (e.g., "stop").
-* @property {XToolCall[]} tools_calls - The reason for finishing (e.g., "stop").
-*/
-
-/**
-* https://docs.x.ai/api/endpoints#chat-completions
-* @typedef {object} XOptions
-* @property {grokModels} [model] - What model to use 
-* @property {Array<*>}         [messages] - the actual prompt  
-* @property {XToolCall[]}        [tools], callable functions  
-* @property {string}              [tool_choice] - Default 'none' when no function, 'auto' when present, or required 
-* @property {Object} [response_format] - Response format
-* @property {string} [response_format.type] - The role of the sender (e.g., "assistant").
-* @property {number}              [temperature] -  What sampling temperature to use, between 0 and 2. 
-* @property {number}              [max_completion_tokens] -  The maximum number of tokens allowed for the generated answer. 
-* @property {number}              [presence_penalty] -  Number between -2.0 and 2.0.  
-* @property {number}              [frequency_penalty] - Number between -2.0 and 2.0. 
-* @property {number}              [top_p] -  Number between -2.0 and 2.0.
-* @property {number}              [n] - How many chat completion choices to generate for each input message. default 1
-* @property {boolean}             [stream] - Chunk/stream request default null
-* @property {boolean}             [parallel_tool_calls] - Multiple calls at once
-* @property {grokReason}        [reasoning_effort] - Who i am 
-* @property {string}              [user] - Who i am 
-* @property {number}              [seed] - see options
-* @property {SearchParameters} [search_parameters] - live search
-* @property {string[]}            [stop] - Up to 4 sequences where the API will stop generating further tokens.  
-*/
-const API_URL = 'https://api.x.ai/v1/chat/completions';
-/** @type {XOptions} */
-const defaultSettings = {
-	model: 'grok-4',
-	messages: [
-		{
-			role: 'system',
-			content: 'Be precise and concise'
-		}
-	],
-	temperature: 0.2,
-	// response_format: { type: 'text' },
-	parallel_tool_calls: true,
-	// reasoning_effort: null,
-	// max_completion_tokens: 2000,
-	// presence_penalty: 0,
-	// frequency_penalty: 0,
-	// top_p: 1,
-	// stop: []
-};
-
-
-/**
-* Get the default headers
-* @returns {object}
-*/
-const getHeaders = () => {
-	if (!process.env['XAIKEY']) {
-		throw new Error('Missing XAIKEY! export XAIKEY=<XAIKEY>')
-	}
-	const KEY = process.env['XAIKEY'];
-	return {
-		'Content-Type': 'application/json',
-		'Authorization': `Bearer ${KEY}`
-	}
-}
-/**
-* Get the text from content
-* @param {import('../../Prompt.js').Content[]} content
-* @returns {string}
-*/
-function getTextFromContent(content) {
-	let res = '';
-	let i = 0;
-	const len = content.length;
-	for (; i < len; i++) {
-		if (content[i].type === 'text') {
-			// @ts-ignore
-			res = `${res}\n${content[i].text} `
-		}
-	}
-	return res.trim();
-}
-/**
-* Convert messages to XAI 
-* @param {Prompt} prompt
-* @returns {Array<*>}
-*/
-const generateHistory = (prompt) => {
-	const messages = prompt.messages
-	const result = [];
-	let i = 0;
-	const len = messages.length;
-	for (; i < len; i++) {
-		const msg = messages[i];
-		const role = msg.role;
-		if (['system', 'assistant', 'user'].includes(role)) {
-			// Get the text
-			const text = getTextFromContent(msg.content);
-			const newMesg = {
-				role,
-				content: text,
-				refusal: null
-			};
-			// Add initial toolcalls
-			const toolCalls = msg.content
-				.filter(item => item.type === 'function_request')
-				.map(req => ({
-					// @ts-ignore
-					id: req.function_request.id,
-					type: "function",
-					function: {
-						// @ts-ignore
-						arguments: req.function_request.parameters,
-						// @ts-ignore
-						name: req.function_request.name,
-					}
-				}));
-			if (toolCalls.length > 0) {
-				newMesg.tool_calls = toolCalls;
-			}
-			result.push(newMesg);
-		} else if (role === 'tool') {
-			const content = msg.content;
-			let it = 0;
-			const lent = content.length;
-			for (; it < lent; it++) {
-				/** @type {import('../..//Prompt.js').FunctionResponse} */
-				// @ts-ignore
-				const item = content[it];
-				if (item.type === 'function_response') {
-					// Add tool function response
-					result.push({
-						role: 'tool',
-						name: item.function_response.name,
-						call_id: item.function_response.call_id,
-						content: item.function_response.response
-					});
-				}
-			}
-		}
-	}
-	return result;
-}
-
-/**
-* Convert a toolset to something openai understands
-* @param {ToolSet} toolset
-* @returns {XToolCall[]}
-*/
-const generateXAIToolCalls = (toolset) => {
-	const list = toolset.list();
-	/** @type {XToolCall[]} */
-	const result = [];
-	list.forEach((item) => {
-		result.push({
-			type: 'function', function: {
-				name: item.name,
-				// @ts-ignore
-				description: item.description,
-				parameters: item.parameters
-			}
-		})
-	});
-	return result;
-}
-
-/**
-* Create an anthropic request
-* @param {Prompt} prompt
-* @param {ToolSet|void} [tools]
-* @param {XOptions} [opts] overwrite default request settings
-* @param {object} [hdrs] - optional headers to pass
-* @returns {XRequest}
-* @throws {Error}
-*/
-const generateRequest = (prompt, tools, opts = {}, hdrs = {}) => {
-	/** @type {XOptions} */
-	const body = { ...defaultSettings, ...opts };
-	const headers = { ...getHeaders(), ...hdrs };
-	// Sanity check
-	// basePromptCheck(prompt);
-	// body.messages = generateXAIMessages(prompt) || [];
-	body.messages = generateHistory(prompt);
-	if (body.messages.length == 0) {
-		throw new Error('No messages found');
-	}
-	body.tools = (tools) ? generateXAIToolCalls(tools) : [];
-	body.tool_choice = (tools) ? tools.toolChoice : '';
-	if (body.tools.length === 0) {
-		delete body.tools;
-		delete body.tool_choice;
-	}
-	return { body, headers, url: API_URL };
-};
-
-// RESPONSE PARSER
-
-/**
-* @typedef {Object} XResponse
-* @property {string} id - The unique identifier for the response.
-* @property {string} object - The type of object returned, typically "chat.completion".
-* @property {number} created - The timestamp of when the response was created.
-* @property {string} model - The model used to generate the response.
-* @property {Array<XChoice>} choices - An array of choice objects containing the response details.
-* @property {XUsage} usage - An object containing token usage information.
-* @property {string} system_fingerprint - The system fingerprint for the response.
-* @property {Object} http_headers - HTTP headers associated with the response.
-*/
-/**
-* @typedef {Object} XChoice
-* @property {number} index - The index of the choice in the response.
-* @property {XMessageResponse} message - The message object containing the role and content.
-* @property {null} logprobs - Log probabilities, typically null.
-* @property {string} finish_reason - The reason why the response finished.
-*/
-/**
-* @typedef {Object} XUsage
-* @property {number} prompt_tokens - The number of tokens in the prompt.
-* @property {number} completion_tokens - The number of tokens in the completion.
-* @property {number} total_tokens - The total number of tokens used.
-*/
-
-const parseMessages = (response, prompt) => {
-	/** @type {import('../../Prompt.js').FunctionRequest[]} */
-	const function_requests = [];
-	const messages = response.choices;
-	if (response.citations && response.citations.length > 0) {
-		const cits = response.citations.map((item, index) => `${index + 1}. ${item}`).join('\n');
-		prompt.add('log', cits);
-	}
-	let i = 0;
-	const len = messages.length;
-	for (; i < len; i++) {
-		const msg = messages[i];
-		if (msg.message.reasoning_content) {
-			// Add reasoning content
-			// Handy for debugging prompts
-			prompt.add('reasoning', msg.message.reasoning_content);
-		}
-		if (msg.refusal) {
-			// Wrong question in relation to policies
-			prompt.add('assistant', msg.refusal);
-			// console.log(msg);
-			continue;
-		}
-		// Add a text message
-		if (
-			msg.message.role === 'assistant' &&
-			typeof msg.message.content === 'string') {
-			prompt.add('assistant', msg.message.content);
-		}
-		// Get function request
-		if (msg.message.tool_calls) {
-			for (const toolCall of msg.message.tool_calls) {
-				function_requests.push(
-					{
-						type: 'function_request',
-						function_request: {
-							name: toolCall.function.name,
-							id: toolCall.id,
-							call_id: toolCall.id,
-							parameters: toolCall.function.arguments
-						}
-					}
-				);
-			}
-		}
-	}
-	if (function_requests.length > 0) {
-		prompt.addMultiModal('assistant', function_requests);
-	}
-}
-
-/**
-* Process an openai response
-* @param {number} duration - the time is MS before and after the request
-* @param {import('@j-o-r/apiserver/types/request.js').FetchResponseObject} res
-* @param {Prompt} prompt
-* @param {ToolSet} [toolset]
-* @returns {Promise<void>}
-* @throws {Error}
-*/
-const parseResponse = async (duration, prompt, res, toolset) => {
-	// @todo - Put some effort in the parsing, this is quick and dirty
-	if (res.status !== 200) {
-		new Error(`${res.status}: res.response`)
-	}
-	const record = prompt.templateRecord();
-	record.model = res.response.model;
-	record.id = res.response.id;
-	record.environment = 'openai';
-	record.isoDate = new Date(res.response.created * 1000).toISOString();
-	record.tokensIn = res.response.usage.prompt_tokens;
-	record.tokensOut = res.response.usage.completion_tokens;
-	record.duration = duration;
-	prompt.addRecord(record);
-	parseMessages(res.response, prompt);
-	if (toolset) {
-		// Inspect for function_request and execute if so
-		await toolset.execute(prompt);
-	}
-}
-
-/**
-* Do a request
-* @param {Prompt} prompt
-* @param {ToolSet|null} toolset
-* @param {XOptions} [options]:
-* @param {number} [counter] - leave empty this counts the number of requests when doing recursive request calls
-* @return {Promise<import('../../Session.js').Message>}
-*/
-async function request(prompt, toolset = null, options, counter = 0) {
-	// Max number of recurusive calls
-	const counterMax = GLOBAL.max_recursive_requests;
-	const start = new Date().getTime();
-	// Generate the request
-	const { url, headers, body } = generateRequest(prompt, toolset, options);
-  prompt.emit(prompt.EVENTS.http_request, {url, counter, body});
-	const res = await doRequest(url, 'POST', headers, body);
-  prompt.emit(prompt.EVENTS.http_response, res);
-	if (res.status !== 200) {
-		throw new Error(`${res.status}: ${JSON.stringify(res.response, null, '  ')}`)
-	}
-	const duration = new Date().getTime() - start;
-	await parseResponse(duration, prompt, res, toolset);
-	counter = 1 + counter;
-	if (counter >= counterMax) {
-		throw new Error('Max number of recursive calls reached');
-	}
-	const lastMessage = prompt.getLastMessage();
-	if (!lastMessage) throw new Error('No message found');
-	const role = lastMessage.role;
-	if (role === 'tool') {
-		// need to do another roundtrip to include the function_responses
-		// Go easy on the speed, do not hit limits to soon
-		await sleep('30s');
-		return request(prompt, toolset, options, counter)
-	} else {
-		return lastMessage
-	}
-}
-export {
-	generateRequest,
-	parseResponse,
-	request
-}

package/lib/AgentClient.js

@@ -1,248 +0,0 @@
-import { WebSocketClient } from '@j-o-r/apiserver';
-/**
- * @module lib/AgentClient
- * @exports default AgentClient
- * Websocket client for AI agent sessions, wrapping a Prompt/ToolSet instance with robust queue-based message handling, auto-reconnect, and epoch-based resets.
- */
-
-/**
- * @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('./ToolSet.js').default} ToolSet
- */
-/**
- * @typedef {Object} WSOptions
- * @property {Prompt} prompt - The prompt session instance.
- * @property {ToolSet} [toolset] - Optional toolset for the prompt.
- * @property {string} description - Custom introduction message for the agent.
- * @property {string} name - Logical name (e.g., 'search', 'code', 'os').
- * @property {string} secret - Websocket server access secret (must match server).
- * @property {string} [url='ws://127.0.0.1:8000/ws'] - WebSocket URL.
- * @property {number} [intervalMs=2000] - Polling interval for queue processing (ms).
- * @example { prompt, name: 'code-agent', secret: 'abc123', url: 'ws://localhost:8001/ws' }
- */
-
-/**
- * AgentClient: WebSocket client wrapper for AI agent sessions.
- * Combines Prompt/ToolSet with WS communication for bidirectional queries, responses, tool calls, and resets.
- * Features: Sequential message queue (one-at-a-time processing), auto-reconnect on close, epoch invalidation for resets.
- * Logs events via console; emits via underlying Prompt (tool_request, tool_error, etc.).
- * @emits tool_request - When tools are requested (via #prompt).
- * @emits tool_error - When tools fail (via #prompt).
- * @example
- * const client = new AgentClient({
- *   prompt: myPrompt,
- *   name: 'code',
- *   description: 'Code execution agent',
- *   secret: 'mysecret',
- *   intervalMs: 1000
- * });
- */
-class AgentClient {
-	/** @private @type {Prompt} */
-	#prompt;
-	/** @private @type {string} */
-	#description = '';
-	/** @private @type {string} */
-	#name;
-	/** @private @type {string} */
-	#secret = '';
-	/** @private @type {import('@j-o-r/apiserver').WebSocketClient} */
-	#ws;
-	/** @private @type {string} */
-	#url = 'ws://127.0.0.1:8000/ws';
-
-	/** @private @type {Array<Object>} Message queue for sequential processing. */
-	#queue = [];
-	/** @private @type {boolean} Flag to prevent reentrant processing. */
-	#processing = false;
-	/** @private @type {number} Epoch counter; increments on reset to invalidate in-flight work. */
-	#epoch = 0;
-
-	/** @private @type {NodeJS.Timeout|null} Interval ID for scheduler. */
-	#intervalId = null;
-	/** @private @type {number} Queue polling interval (ms). */
-	#intervalMs = 2000;
-
-	/**
-	 * Initializes the AgentClient with configuration options.
-	 * Registers Prompt events for logging and starts the WebSocket connection.
-	 * @param {WSOptions} options - Configuration object.
-	 * @throws {TypeError} If required options (e.g., prompt, secret) are invalid/missing.
-	 * @example See WSOptions.
-	 */
-	constructor(options) {
-		if (options.url) this.#url = options.url;
-		this.#prompt = options.prompt;
-		this.#description = options.description;
-		this.#name = options.name;
-		this.#secret = options.secret;
-		if (typeof options.intervalMs === 'number') this.#intervalMs = Math.max(1, options.intervalMs);
-		this.#registerPromptEvents();
-		this._start();
-	}
-
-	/**
-	 * @private
-	 * Registers Prompt events for logging tool requests/errors.
-	 * @returns {void}
-	 */
-	#registerPromptEvents() {
-		const events = Object.keys(this.#prompt.EVENTS);
-		events.forEach((evt) => {
-			this.#prompt.on(evt, (_msg) => {
-		 		console.log(`** ${this.#name} e:${evt}**`);
-		 		if (evt === 'tool_request') {
-		 			console.log(`tool execute: ${_msg.name} ${_msg.call_id}`);
-		 		} else if (evt === 'tool_error') {
-		 			console.log(`tool error:`);
-		 			console.log(JSON.stringify(_msg, null, '  '));
-		 		}
-			});
-		});
-	}
-
-	/**
-	 * @private
-	 * Starts the WebSocket connection, sends introduction, sets up handlers.
-	 * Auto-retries on close after 5s.
-	 * @returns {void}
-	 */
-	_start() {
-		const url = this.#url + '?wssrc_id=' + this.#secret;
-		this.#ws = new WebSocketClient(url);
-		this.#ws.onopen = () => {
-			this.#ws.send(JSON.stringify({
-				action: 'agent_introduction',
-				name: this.#name,
-				content: this.#description,
-				id: new Date().getTime()
-			}));
-			console.log('introduction_send:>>');
-			console.log(this.#name);
-			console.log(this.#description);
-		};
-		this.#ws.onmessage = (m) => {
-			this.incoming(m);
-		};
-		this.#ws.onclose = () => {
-			console.error('CLOSE: Lost Connection, retry in 5 seconds');
-			this.#stopInterval();
-			setTimeout(() => {
-				this._start();
-			}, 5000);
-		};
-		this.#ws.onerror = (e) => {};
-	}
-
-	/**
-	 * Enqueues an incoming WebSocket message and starts interval processing if needed.
-	 * Immediately handles 'reset' actions (clears queue, resets prompt, increments epoch).
-	 * @param {MessageEvent} e - Raw WebSocket message event.
-	 * @returns {void}
-	 * @throws {SyntaxError} If JSON parse fails.
-	 */
-	incoming(e) {
-		let message;
-		try {
-			message = JSON.parse(e.data);
-		} catch (err) {
-			console.error('Invalid JSON in incoming message');
-			return;
-		}
-		if (message?.action === "reset") {
-			console.log("<RESET:incoming>");
-			this.#epoch++;
-			this.#queue = [];
-			this.#stopInterval();
-			this.#prompt.reset();
-			return;
-		}
-		this.#queue.push(message);
-		this.#startInterval();
-	}
-
-	/**
-	 * @private
-	 * Starts the interval ticker to process one queued message per tick.
-	 * Idempotent; skips if already running.
-	 * @returns {void}
-	 */
-	#startInterval() {
-		if (this.#intervalId) return;
-		this.#intervalId = setInterval(() => {
-			void this.#processOne();
-		}, this.#intervalMs);
-	}
-
-	/**
-	 * @private
-	 * Stops the processing interval.
-	 * @returns {void}
-	 */
-	#stopInterval() {
-		if (this.#intervalId) {
-			clearInterval(this.#intervalId);
-			this.#intervalId = null;
-		}
-	}
-
-	/**
-	 * @private
-	 * Processes exactly one queued message (guards reentrancy).
-	 * Stops interval if queue empty post-process.
-	 * @returns {Promise&lt;void&gt;}
-	 */
-	async #processOne() {
-		if (this.#processing) return;
-		const message = this.#queue.shift();
-		if (!message) {
-			this.#stopInterval();
-			return;
-		}
-		this.#processing = true;
-		try {
-			const epochAtStart = this.#epoch;
-			await this.#handleMessage(message, epochAtStart);
-		} finally {
-			this.#processing = false;
-			if (this.#queue.length === 0) this.#stopInterval();
-		}
-	}
-
-	/**
-	 * @private
-	 * Handles a single enqueued message (query/response/reset).
-	 * Sends responses/errors back via WS.
-	 * @param {Object} message - Parsed message.
-	 * @param {number} epochAtStart - Epoch at start; aborts if changed.
-	 * @returns {Promise&lt;void&gt;}
-	 */
-	async #handleMessage(message, epochAtStart) {
-		if (message.action === 'agent_query') {
-			const id = message.id;
-			try {
-				console.log('IN:>>\n' + message.content);
-				const content = await this.#prompt.call(message.content);
-				console.log('OUT:>>\n' + content);
-				this.#ws.send(JSON.stringify({ action: 'agent_response', content, id }));
-			} catch (err) {
-				this.#ws.send(JSON.stringify({ action: 'agent_error', content: String(err?.message || err), id }));
-			}
-		} else if (message.action === 'reset') {
-			console.log('<RESET>');
-			this.#queue = [];
-			this.#epoch++;
-			this.#prompt.reset();
-		}
-	}
-}
-
-export default AgentClient;