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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@j-o-r/hello-dave",
   "type": "module",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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",

package/types/AgentClient.d.ts

@@ -9,67 +9,101 @@ export type Prompt = import("./Prompt.js").default;
 export type ToolSet = import("./ToolSet.js").default;
 export type WSOptions = {
     /**
-     * - The prompt session
+     * - The prompt session instance.
      */
     prompt: Prompt;
     /**
-     * - The toolset
+     * - Optional toolset for the prompt.
      */
     toolset?: import("./ToolSet.js").default | undefined;
     /**
-     * - Custom introduction message.
+     * - Custom introduction message for the agent.
      */
     description: string;
     /**
-     * - Logical name: e.g. search, code, os, support.
+     * - Logical name (e.g., 'search', 'code', 'os').
      */
     name: string;
     /**
-     * - Websocket server access secret.
+     * - Websocket server access secret (must match server).
      */
     secret: string;
+    /**
+     * - WebSocket URL.
+     */
     url?: string | undefined;
     /**
-     * - How often to pull one message from the queue.
+     * - Polling interval for queue processing (ms).
      */
     intervalMs?: number | undefined;
 };
 /**
-* @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
-*/
+ * @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
-* @property {ToolSet} [toolset] - The toolset
-* @property {string} description - Custom introduction message.
-* @property {string} name - Logical name: e.g. search, code, os, support.
-* @property {string} secret - Websocket server access secret.
-* @property {string} [url='ws://127.0.0.1:8000/ws?params=1234']
-* @property {number} [intervalMs=250] - How often to pull one message from the queue.
-*/
+ * @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' }
+ */
 /**
-* Websocket Client
-* Wrapper combining a session and a websocket
-*/
+ * 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
+ * });
+ */
 declare class AgentClient {
     /**
-     * Creates an instance of CLILoader.
-     * @param {WSOptions} options - The options to configure the CLILoader.
+     * 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: WSOptions);
-    _start(): void;
     /**
-    * Enqueue an incoming websocket message and trigger the processor.
-    */
-    incoming(e: any): void;
+     * @private
+     * Starts the WebSocket connection, sends introduction, sets up handlers.
+     * Auto-retries on close after 5s.
+     * @returns {void}
+     */
+    private _start;
+    /**
+     * 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: MessageEvent): void;
     #private;
 }

package/types/AgentManager.d.ts

@@ -5,101 +5,95 @@ export type OAOptions = import("./API/openai.com/reponses/text.js").OAOptions;
 export type ANTHOptions = import("./API/anthropic.com/text.js").ANTHOptions;
 export type Setup = {
     /**
-     * - Initial system prompt
+     * - Initial system prompt.
      */
     prompt: string;
     /**
-     * - Model options
+     * - API model options.
      */
     options: XAIOptions | OAOptions | XOptions | ANTHOptions;
     /**
-     * - AI endpoint to use
+     * - AI provider.
      */
     api: "gpt" | "xai" | "claude";
     /**
-     * - The size in tokens for the context/session
+     * - Token limit for context.
      */
     contextWindow?: number | undefined;
     /**
-     * -
+     * - Toolset activation mode.
      */
-    toolsetMode?: void | "auto" | "required" | undefined;
+    toolsetMode?: "auto" | "required" | null | undefined;
     /**
-     * - verbose output
+     * - Enable verbose output.
      */
     debug?: boolean | undefined;
 };
 export type Options = {
     /**
-     * - Agent name
+     * - Agent name (validated /^[a-z_0-9]{2,}$/).
      */
     name: string;
     /**
-     * - Secret string for WS access authorisation (server and client secrets should match)
+     * - WS auth secret (base64-encoded).
      */
     secret: string;
     /**
-     * - path to session/record storage
+     * - Session cache directory.
      */
     cachePath?: string | undefined;
 };
-/**
-* @typedef {import('./API/x.ai/text.js').XOptions} XOptions
-* @typedef {import('./API/x.ai/responses.js').XAIOptions} XAIOptions
-* @typedef {import('./API/openai.com/reponses/text.js').OAOptions} OAOptions
-* @typedef {import('./API/anthropic.com/text.js').ANTHOptions} ANTHOptions
-*/
-/**
-* @typedef {Object} Setup
-* @property {string} prompt - Initial system prompt
-* @property {XAIOptions|OAOptions|XOptions|ANTHOptions} options - Model options
-* @property {'gpt'|'xai'|'claude'} api - AI endpoint to use
-* @property {number} [contextWindow] - The size in tokens for the context/session
-* @property {'auto'|'required'|void} [toolsetMode] -
-* @property {boolean} [debug] - verbose output
-*/
-/**
-* @typedef {Object} Options
-* @property {string} name - Agent name
-* @property {string} secret - Secret string for WS access authorisation (server and client secrets should match)
-* @property {string} [cachePath] - path to session/record storage
-*/
 declare class AgentManager {
     /**
-    * @param {Options} options
-    */
+     * Initializes AgentManager with base options.
+     * Validates name regex; encodes secret.
+     * @param {Options} options - Base configuration.
+     * @throws {Error} Invalid name (regex) or options.
+     * @chainable
+     */
     constructor(options: Options);
     /**
-    * @param {Setup} setup
-    */
-    setup(setup: Setup): this;
+     * Configures the Prompt/Session/ToolSet with API adaptor.
+     * Adds system prompt; chains to start().
+     * @param {Setup} setup - AI setup details.
+     * @returns {AgentManager} This instance (chainable).
+     * @throws {Error} Invalid setup.
+     * @example mgr.setup({ prompt: 'You are a coder...', api: 'gpt', options: { model: 'gpt-4o' } });
+     */
+    setup(setup: Setup): AgentManager;
     /**
-    * Direct call to the prompt
-    * @param {string} input
-    * @returns {Promise<string>}
-    */
-    directCall(input: string): Promise<string>;
-    /** @returns {Prompt} */
+     * Direct synchronous call to the underlying Prompt.
+     * @param {string} input - User input.
+     * @returns {Promise&lt;string&gt;} Response.
+     * @throws {Error} No setup.
+     */
+    directCall(input: string): Promise<any> & lt;
+    /** @returns {Prompt} Underlying Prompt instance. */
     getPrompt(): Prompt;
-    /** @returns {ToolSet|void} */
-    getToolset(): ToolSet | void;
-    /** @returns {Promise<import('./fafs.js').EnvironmentInfo>} */
-    environment(): Promise<import("./fafs.js").EnvironmentInfo>;
+    /** @returns {ToolSet|null} Toolset if configured. */
+    getToolset(): ToolSet | null;
+    /** @returns {Promise&lt;import('./fafs.js').EnvironmentInfo&gt;} System env info. */
+    environment(): Promise<any> & lt;
     /**
-     * Adds a pre-defined generic tool from lib/genericToolset.js to this agent's ToolSet.
-     * @param {'execute_bash_script'|'execute_remote_script'|'get_user_env'|'history_search'|'javascript_interpreter'|'memory_recall'|'memory_write'|'open_link'|'read_file'|'send_email'|'syntax_check'|'write_file'} name - Valid generic tool name (validated /^[a-z_0-9]{2,}$/).
-     * @throws {Error} If toolset not initialized or tool not found in pool.
+     * Adds a pre-defined generic tool from toolsPool to this agent's ToolSet.
+     * @param {'execute_bash_script'|'execute_remote_script'|'get_user_env'|'history_search'|'javascript_interpreter'|'memory_recall'|'memory_write'|'open_link'|'read_file'|'send_email'|'syntax_check'|'write_file'} name - Tool name.
+     * @throws {Error} Invalid name, no toolset, or tool missing.
+     * @example mgr.addGenericToolcall('read_file');
      */
     addGenericToolcall(name: "execute_bash_script" | "execute_remote_script" | "get_user_env" | "history_search" | "javascript_interpreter" | "memory_recall" | "memory_write" | "open_link" | "read_file" | "send_email" | "syntax_check" | "write_file"): void;
     /**
-     * Smart launcher: Dispatches to CLI/server/attach/direct. Auto-gens cliIntro/desc if empty.
-     * @param {number} [servePort] - Server port (if no input).
-     * @param {string} [connectUrl] - WS to attach. e.g. ws://127.0.0.1:8091/ws
-     * @param {string} [cliIntro=""] - CLI intro (auto-gen if falsy).
-     * @param {string} [toolName=""] - name /^[a-z_0-9]{2,}$/ Tool name for server/attach (defaults to agent.name).
-     * @param {string} [toolDescription=""] - Tool desc (auto-gen if falsy).
+     * Smart launcher: CLI (default), server (servePort), or client (connectUrl).
+     * Auto-generates intros/descriptions if empty.
+     * @param {number} [servePort] - Launch server on port.
+     * @param {string} [connectUrl] - Connect as client to WS.
+     * @param {string} [cliIntro=""] - CLI intro text.
+     * @param {string} [toolName=""] - Tool/server name (falls back to #name).
+     * @param {string} [toolDescription=""] - Tool desc.
+     * @returns {Promise&lt;void&gt;}
+     * @throws {Error} No setup; invalid names/ports.
+     * @example mgr.start(8000); // Server\nmgr.start(undefined, 'ws://other:8001/ws'); // Client\nmgr.start(); // CLI
      */
-    start(servePort?: number, connectUrl?: string, cliIntro?: string, toolName?: string, toolDescription?: string): Promise<void>;
+    start(servePort?: number, connectUrl?: string, cliIntro?: string, toolName?: string, toolDescription?: string): Promise<any> & lt;
     #private;
 }
 import { Prompt } from './index.js';

package/types/AgentServer.d.ts

@@ -1,42 +1,89 @@
 export default AgentServer;
-export type Client = import("../node_modules/@j-o-r/apiserver/types/ClientWrapper.d.ts").ClientWrapper;
+export type Client = import("@j-o-r/apiserver/types/ClientWrapper.d.ts").ClientWrapper;
 export type Prompt = import("./Prompt.js").default;
 export type ToolSet = import("./ToolSet.js").default;
 export type Session = import("./Session.js").default;
-export type AuthFunction = (conn: import("@j-o-r/apiserver/types/WebSocketServer.js").WebSocketConnection, req: any) => Promise<boolean>;
+export type MessageContent = string | object;
+export type Message = {
+    /**
+     * - Action type (must be in ACTIONS).
+     */
+    action: string;
+    content?: MessageContent | undefined;
+    id?: string | undefined;
+};
 export type AgentServerOptions = {
+    /**
+     * - Server/agent name.
+     */
     name: string;
     /**
-     * - server access secret
+     * - Access secret (matches client secrets).
      */
     secret: string;
+    /**
+     * - Server description.
+     */
     description: string;
+    /**
+     * - Prompt instance.
+     */
     prompt: Prompt;
+    /**
+     * - Session manager.
+     */
     session: Session;
-    auth?: AuthFunction | undefined;
     /**
-     * - default 8000
+     * - Custom auth function.
+     */
+    auth?: AuthFunction;
+    /**
+     * - Listen port (&gt;=1024).
      */
     port?: number | undefined;
+    /**
+     * - Verbose logging.
+     */
     debug?: boolean | undefined;
 };
+/**
+ * AgentServer: Core WebSocket server class.
+ * Exposes connected agents as tools; handles user CLI/WS interactions, auth, sessions.
+ * Starts on localhost; broadcasts resets.
+ * Logs events via console; emits via Prompt.
+ * @emits tool_request - Tool calls (via #prompt).
+ * @emits tool_error - Tool failures (via #prompt).
+ * @example
+ * const server = new AgentServer({
+ *   name: 'main',
+ *   prompt: myPrompt,
+ *   session: mySession,
+ *   secret: 'abc',
+ *   port: 8000,
+ *   debug: true
+ * });
+ */
 declare class AgentServer {
     /**
-    * @param {AgentServerOptions} options
-    */
+     * Initializes and starts the AgentServer.
+     * Validates port, sets up Prompt event logging, launches WS server.
+     * @param {AgentServerOptions} options - Server configuration.
+     * @throws {Error} If port &lt; 1024.
+     * @example See AgentServerOptions.
+     */
     constructor(options: AgentServerOptions);
     /**
-    * @private
-    * Returns a Dynamic Toolset
-    * With registered WS clients as toolcalls
-    * A deamon start on local host 127.0.0.1, always
-    * @returns {Promise<void>}
-    */
+     * @private
+     * Launches the WS server with handlers for messages, connections, closes.
+     * Defines HTTP / API index endpoint.
+     * @returns {Promise&lt;void&gt;}
+     */
     private _start;
     /**
-    * Send a reset messages to all clients
-    * reset will start a new session
-    */
+     * Broadcasts a reset message to all connected clients (starts new sessions).
+     * @returns {void}
+     * @fires reset - Via underlying prompt/clients.
+     */
     resetAll(): void;
     #private;
 }

package/types/Cli.d.ts

@@ -8,45 +8,91 @@ export type ANTHOptions = import("./API/anthropic.com/text.js").ANTHOptions;
 export type Prompt = import("./Prompt.js").default;
 export type Session = import("./Session.js").default;
 export type ToolSet = import("./ToolSet.js").default;
+/**
+ * Configuration options for initializing the Cli class.
+ */
 export type CLIOptions = {
     /**
-     * - The prompt session
+     * - The Prompt instance for handling AI interactions.
      */
     prompt: Prompt;
     /**
-     * - Session  Cache
+     * - The Session instance for managing conversation history.
      */
     session: Session;
     /**
-     * - The toolset
+     * - Optional ToolSet for tool integrations.
      */
     toolset?: import("./ToolSet.js").default | undefined;
     /**
-     * - Custom introduction message.
+     * - Custom introduction message (appended to default INTRO).
      */
     description?: string | undefined;
     /**
-     * - Custom help message.
+     * - Custom help message (overrides default HELP).
      */
     help?: string | undefined;
 };
 /**
- * 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
  */
 declare class Cli {
     /**
-     * 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: CLIOptions);
+    /**
+     * Prints detailed info about current session and prompt, plus description.
+     * Triggered by Alt+i.
+     */
     printInfo(): void;
     /**
-     * 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
      */
     start(s?: string): Promise<void>;
+    /**
+     * 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>}
+     */
     loadSession(): Promise<void>;
+    /**
+     * Resets the prompt (clears context), reprints info, triggered by Alt+r.
+     * @returns {Promise<void>}
+     */
     reset(): Promise<void>;
     #private;
 }
+/**
+ * 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.
+ */
+export function copyToClipboard(text: string): Promise<void>;

package/types/Prompt.d.ts

@@ -137,12 +137,44 @@ export type Message = {
     ts?: number | undefined;
 };
 /**
+* 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.
 *
-* @fires Prompt#add
-* Event: message added
+* 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)
 *
-* @event Prompt#add
-* @type {Message}
+* 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)
+*
+* @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
 */
 declare class Prompt {
     /**

package/types/Session.d.ts

@@ -2,28 +2,42 @@ export default Session;
 export type Message = import("./Prompt.js").Message;
 export type Record = import("./Prompt.js").Record;
 /**
- */
+* Session class for managing persistent chat sessions with Prompt.
+*/
 declare class Session {
     /**
-    * 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: string, prompt: Prompt, storage?: string);
-    name: string | undefined;
+    /** @type {string} Sanitized prompt name (public readonly). */
+    name: string;
+    /**
+    * Returns current session information.
+    *
+    * @returns {string} Formatted info: Name, Session, SessionCount, Path.
+    */
     info(): string;
+    /**
+    * Lists unique session names (processed: remove _\d+, _ → space).
+    *
+    * @returns {string[]} Array of unique session names.
+    */
     sessionList(): string[];
     /**
-    * 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: string): Message[];
     /**
-    * Remove all previous sessions and records
+    * Empties all caches: sessions, records, logs.
     */
     empty(): void;
     #private;