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

package/types/ToolSet.d.ts

@@ -22,6 +22,9 @@ export type TSTool = {
      * - JS JSON schema
      */
     parameters: TSSchema;
+    /**
+     * - The async method to execute
+     */
     method: (arg0: object) => Promise<any>;
 };
 export type TSToolListItem = {
@@ -38,57 +41,71 @@ export type TSToolListItem = {
      */
     parameters: TSSchema;
 };
+/**
+ * @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.
+ */
 declare class ToolSet {
     /**
-    * @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?: string);
     /**
-    * 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(): number;
     /**
-    * 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: string, description: string, parameters: TSSchema, method: (arg0: object) => Promise<any>): void;
     /**
-    * 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: string): TSTool;
     /**
-    * 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: string): void;
     /**
-    * 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: string): boolean;
     /**
-    * 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(): TSToolListItem[];
+    /**
+     * Getter for the current tool choice setting.
+     * @returns {string} The tool choice: 'auto', 'none', or 'required'
+     */
     get toolChoice(): string;
     /**
-    * 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
+     */
     call(name: string, params: object): Promise<any>;
     /**
-     * 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>}
      */
     execute(prompt: Prompt): Promise<void>;
     #private;

package/types/fafs.d.ts

@@ -1,47 +1,90 @@
 export type EnvironmentInfo = {
     /**
-     * - User's name
+     * - User's full name (from passwd GECOS field)
      */
     name: string;
     /**
-     * - Linux OS / PROC
+     * - System information (OS release, architecture, kernel, cwd)
      */
     system: string;
+    /**
+     * - City from external IP geolocation
+     */
     city: string;
+    /**
+     * - Region/State from IP
+     */
     region: string;
+    /**
+     * - Country from IP
+     */
     country: string;
+    /**
+     * - Timezone from IP
+     */
     timezone: string;
+    /**
+     * - External IP address
+     */
     external_ip: string;
     /**
-     * - current working folder
+     * - Current working directory (relative to home as ~)
      */
     cwd: string;
 };
 import { jsType } from '@j-o-r/sh';
-export namespace GLOBAL {
-    export let max_recursive_requests: number;
-    export { APP_CACHE as default_cache };
-    export let secret: string;
-}
 /**
-* Gather information about this environment
-* @returns {Promise<EnvironmentInfo>}
-*/
-export function env(): Promise<EnvironmentInfo>;
+ * 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 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
-*/
+ * @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
+ */
+export const GLOBAL: Object;
+/**
+ * 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);
+ */
+export function env(): Promise<EnvironmentInfo>;
 /**
-* @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"
+ */
 export function systemInfo(): Promise<string>;
-declare const APP_CACHE: any;
 export { jsType };

package/types/wsCli.d.ts

@@ -1,3 +1,17 @@
 #!/usr/bin/env -S node
 declare function _default(connectUrl: string, secret?: string): void;
 export default _default;
+export type WsMessage = {
+    /**
+     * - Action type (e.g., 'user_request')
+     */
+    action: string;
+    /**
+     * - Message content
+     */
+    content: string;
+    /**
+     * - Unique message ID
+     */
+    id: number;
+};

package/types/wsIO.d.ts

@@ -10,12 +10,16 @@
 * 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 function wsio(connectUrl: string, secret?: string, action: "user_request" | "user_info" | "user_reset", input?: string): Promise<wsResponse>;
+export default function wsio(connectUrl: string, secret?: string, action: "user_request" | "user_info" | "user_reset", input?: string): Promise<any> & lt;
 export type wsResponse = {
     action: string;
     content: string;

package/utils/search_sessions.sh

@@ -1,73 +1,120 @@
 #!/bin/bash
+# v2: Role-filtered (user/assistant only), condense per-session/dir, ultra token-efficient.
+# Usage: $0 <query> [--brief] [--all-roles] [--limit=10] [--max-snip=3]
 
-# No set -e to avoid unexpected exits; use explicit checks
 set -uo pipefail
 
-if [ $# -eq 0 ]; then
-    echo "Usage: $0 <search_query_or_regex>"
-    echo "  Searches filenames & content in all .cache/[app]/[prompt]/sessions/*.ndjson"
-    echo "  Shows matching sessions/files with context (grep -i -C5, line nums)."
-    echo "  Quote multi-word/regex: $0 \"package.json\" or $0 \"(hdTodo|todo)\""
-    exit 1
-fi
+usage() {
+  echo "Usage: $0 <query> [--brief] [--all-roles] [--limit=10] [--max-snip=3]"
+  echo "  Role-filtered snippets (user/assistant), condensed per session dir."
+  exit 1
+}
+
+[ $# -eq 0 ] && usage
 
 QUERY="$1"
-echo "🔍 Searching sessions for (case-insensitive regex): '$QUERY'"
-echo "=================================================================="
-echo ""
+LIMIT=10
+MAX_SNIP=3
+BRIEF=false
+ROLE_FILTER=true  # Default: user/assistant only
+shift
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --brief) BRIEF=true; shift ;;
+    --all-roles) ROLE_FILTER=false; shift ;;
+    --limit=*) LIMIT="${1#*=}"; shift ;;
+    --max-snip=*) MAX_SNIP="${1#*=}"; shift ;;
+    --limit) LIMIT="$2"; shift 2 ;;
+    --max-snip) MAX_SNIP="$2"; shift 2 ;;
+    *) echo "Unknown: $1"; usage ;;
+  esac
+done
 
-total_matches=0
-session_count=0
+# 1st pass: matching sessions/files
+declare -a matching_sessions=()
+total_files=0
+scanned=0
 
-# Process substitution avoids subshell
-while IFS= read -r -d '' sess_dir; do
+while IFS= read -r -d '' sess_dir <&3; do
   [ -d "$sess_dir" ] || continue
+  ((scanned++))
+
+  files_matched=0
+  shopt -s nullglob
+  for file in "$sess_dir"/*.ndjson; do
+    base=$(basename "$file" .ndjson)
+    has_match=false
+    # Filename
+    if echo "$base" | grep -qiE "$QUERY"; then
+      has_match=true
+    # Content (role-filtered if enabled)
+    elif ! $BRIEF && [ "$ROLE_FILTER" = true ] && \
+         awk -v q="$QUERY" 'tolower($0) ~ tolower(q) && /"role"\s*:\s*"(user|assistant)"/ {exit 0} END{exit !NR}' "$file" 2>/dev/null; then
+      has_match=true
+    elif ! $BRIEF && [ "$ROLE_FILTER" = false ] && grep -qiE -m1 "$QUERY" "$file" 2>/dev/null; then
+      has_match=true
+    fi
+    [ "$has_match" = true ] && ((files_matched++))
+  done
+  shopt -u nullglob
+  [ $files_matched -gt 0 ] || continue
+  matching_sessions+=("$sess_dir")
+  ((total_files += files_matched))
+done 3< <(find .cache -mindepth 3 -maxdepth 5 -type d -name sessions -print0 2>/dev/null | sort -rz | head -"$LIMIT")
+
+[ $total_files -eq 0 ] && exit 0
 
-  session_count=$((session_count + 1))
-  app_name=$(basename "$(dirname "$(dirname "$sess_dir")")")
-  prompt_name=$(basename "$(dirname "$sess_dir")")
-  mod_time=$(stat -c %Y "$sess_dir" 2>/dev/null || echo 0)
-  date_str=$(date -d "@$mod_time" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "unknown")
+echo "🔍 $QUERY: $total_files files / ${#matching_sessions[@]} sessions (limit=$LIMIT)"
+echo ===
 
-  echo "📁 $app_name/$prompt_name ($date_str)"
-  echo "   $sess_dir"
-  echo "   -------------------------------------------------"
+# 2nd pass: condensed output
+for sess_dir in "${matching_sessions[@]}"; do
+  app=$(basename "$(dirname "$(dirname "$sess_dir")")")
+  prompt=$(basename "$(dirname "$sess_dir")")
+  time=$(stat -c %Y "$sess_dir" 2>/dev/null | xargs -I{} date -d "@{}" '+%H:%M' 2>/dev/null || echo ??)
 
-  dir_matches=0
+  echo "📁 $app/$prompt ($time)"
+  echo ---
+
+  dir_count=0
+  all_snips=""  # Condense all files' snippets here
   shopt -s nullglob
-  for ndjson_file in "$sess_dir"/*.ndjson; do
-    [ -f "$ndjson_file" ] || continue
-
-    fname_base=$(basename "$ndjson_file" .ndjson)
-    fname=$(echo "$fname_base" | sed 's/__/ /g' | sed 's/_[0-9]*$//' | fold -w70 | head -1)
-    fname_short="${fname:0:70}..."
-
-    # Filename match
-    if echo "$ndjson_file" | grep -qiE "$QUERY" || echo "$fname_base" | grep -qiE "$QUERY"; then
-      echo "  💾 FILENAME: $fname_short"
-      dir_matches=$((dir_matches + 1))
-      total_matches=$((total_matches + 1))
+  for file in "$sess_dir"/*.ndjson; do
+    [ -f "$file" ] || continue
+    base=$(basename "$file" .ndjson)
+    name=$(echo "$base" | sed 's/__/ /g; s/_[0-9]*$//' | fold -w30 | sed -E 's/(.{27}).*/\1.../') || name="$base..."
+
+    printed=false
+    # Filename
+    if echo "$base" | grep -qiE "$QUERY"; then
+      echo "  💾 $name"
+      printed=true
     fi
 
-    # Content matches
-    content_matches=$(grep -iHn -C 5 -E -m 20 "$QUERY" "$ndjson_file" 2>/dev/null || true)
-    if [ -n "$content_matches" ]; then
-      echo "  📄 CONTENT in $fname_short:"
-      echo "$content_matches"
-      echo ""
-      dir_matches=$((dir_matches + 1))
-      total_matches=$((total_matches + 1))
+    # Content snippets (role-filtered awk)
+    if ! $BRIEF; then
+      if [ "$ROLE_FILTER" = true ]; then
+        snips=$(awk -v q="$QUERY" 'tolower($0) ~ tolower(q) && /"role"\s*:\s*"(user|assistant)"/ { print substr($0, 1, 100) }' "$file" 2>/dev/null | head -"$MAX_SNIP" | paste -sd'; ')
+      else
+        snips=$(grep -iE "$QUERY" "$file" 2>/dev/null | cut -c1-100 | head -"$MAX_SNIP" | paste -sd'; ')
+      fi
+      [ -n "$snips" ] && {
+        all_snips+="$snips; "
+        printed=true
+      }
     fi
+    [ "$printed" = true ] && ((dir_count++))
   done
   shopt -u nullglob
 
-  if [ $dir_matches -eq 0 ]; then
-    echo "  (no matches)"
-  fi
-  echo ""
-done < <(find .cache -mindepth 3 -maxdepth 5 -type d -name "sessions" -print0 2>/dev/null | sort -rz | head -30)
+  # Condensed session block
+  [ -n "$all_snips" ] && {
+    echo "  📄 Session ($dir_count files): $(echo "$all_snips" | fold -w90 | sed ':a;N;$!ba;s/\n/ /g' | cut -c1-180)"
+    echo
+  }
+  echo "  ($dir_count files)"
+  echo
+done
 
-echo "✅ $total_matches matches across $session_count sessions."
-if [ $total_matches -eq 0 ]; then
-  echo "💡 Tip: Broader query? e.g. 'todo', regex '(package|bin)' or check spelling."
-fi
+echo "✅ $total_files files / ${#matching_sessions[@]} sessions (scanned $scanned)"