@j-o-r/hello-dave 0.0.0

package/lib/promptHelpers.js

@@ -0,0 +1,132 @@
+// Helper utilities for Prompt: pruning resolved tool IO and truncation
+// ESM module
+
+const MESSAGE_TYPES = {
+  TEXT: 'text',
+  IMAGE_URL: 'image_url',
+  AUDIO_URL: 'audio_url',
+  FUNCTION_REQUEST: 'function_request',
+  FUNCTION_RESPONSE: 'function_response'
+};
+
+function lastAssistantTextIndex(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.sticky) continue;
+    if (m.role === 'assistant' && Array.isArray(m.content) && m.content.some(c => c.type === MESSAGE_TYPES.TEXT)) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+function lastUserIndexBefore(messages, cutoff) {
+  for (let i = cutoff - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m.sticky) continue;
+    if (m.role === 'user') return i;
+  }
+  return -1;
+}
+
+function getCallKey(obj) {
+  if (!obj) return undefined;
+  const cid = obj.call_id || obj.id;
+  if (typeof cid === 'string' && cid.trim()) return cid;
+  return undefined;
+}
+
+export function pruneResolvedToolIOByCallIdExceptLast(messages, keepMode = 'lastCall') {
+  if (!Array.isArray(messages) || messages.length === 0) return false;
+
+  // Gather requests/responses by call id
+  const requests = new Map(); // id -> [{msgIndex, contentIndex}]
+  const responses = new Map();
+
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!Array.isArray(m.content)) continue;
+    for (let j = 0; j < m.content.length; j++) {
+      const c = m.content[j];
+      if (c && c.type === MESSAGE_TYPES.FUNCTION_REQUEST) {
+        const key = getCallKey(c.function_request);
+        if (key) {
+          if (!requests.has(key)) requests.set(key, []);
+          requests.get(key).push({ msgIndex: i, contentIndex: j });
+        }
+      } else if (c && c.type === MESSAGE_TYPES.FUNCTION_RESPONSE) {
+        const key = getCallKey(c.function_response);
+        if (key) {
+          if (!responses.has(key)) responses.set(key, []);
+          responses.get(key).push({ msgIndex: i, contentIndex: j });
+        }
+      }
+    }
+  }
+
+  // Determine resolved calls (have both request and response)
+  const resolved = [];
+  for (const [key, resArr] of responses.entries()) {
+    if (requests.has(key)) {
+      // use last response index to order recency
+      const lastResp = resArr[resArr.length - 1];
+      resolved.push({ key, lastRespIndex: lastResp.msgIndex });
+    }
+  }
+  if (resolved.length <= 1) return false; // nothing or only one to keep
+
+  // Cutoff = last assistant text; if none, use end
+  const cutoff = (() => {
+    const idx = lastAssistantTextIndex(messages);
+    return idx === -1 ? messages.length : idx;
+  })();
+
+  // Only consider resolved whose last response is before cutoff
+  const eligible = resolved.filter(r => r.lastRespIndex < cutoff);
+  if (eligible.length <= 1) return false;
+
+  let keepKeys = new Set();
+  if (keepMode === 'lastTurn') {
+    const userIdx = lastUserIndexBefore(messages, cutoff);
+    for (const r of eligible) {
+      if (r.lastRespIndex > userIdx) keepKeys.add(r.key);
+    }
+  } else {
+    // keep only most recent response (highest index before cutoff)
+    let latest = eligible[0];
+    for (const r of eligible) {
+      if (r.lastRespIndex > latest.lastRespIndex) latest = r;
+    }
+    keepKeys.add(latest.key);
+  }
+
+  const pruneKeys = new Set(eligible.map(e => e.key).filter(k => !keepKeys.has(k)));
+  if (pruneKeys.size === 0) return false;
+
+  // Remove matching content items; delete empty messages
+  let changed = false;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (!Array.isArray(m.content) || m.content.length === 0) continue;
+    const newContent = [];
+    for (let j = 0; j < m.content.length; j++) {
+      const c = m.content[j];
+      if (c && c.type === MESSAGE_TYPES.FUNCTION_REQUEST) {
+        const key = getCallKey(c.function_request);
+        if (key && pruneKeys.has(key)) { changed = true; continue; }
+      } else if (c && c.type === MESSAGE_TYPES.FUNCTION_RESPONSE) {
+        const key = getCallKey(c.function_response);
+        if (key && pruneKeys.has(key)) { changed = true; continue; }
+      }
+      newContent.push(c);
+    }
+    if (newContent.length !== m.content.length) {
+      m.content = newContent;
+    }
+    if (m.content.length === 0) {
+      messages.splice(i, 1);
+    }
+  }
+  return changed;
+}
+

package/lib/testToolset.js

@@ -0,0 +1,42 @@
+import ToolSet from '../lib/ToolSet.js'
+// Generic TEST toolset
+const tools = new ToolSet('auto');
+tools.add(
+	'get_current_weather', // name
+	'Get the current weather in a given location', // desciption
+	{
+		type: 'object',
+		properties: {
+			location: {
+				type: 'string',
+				description: 'The city and country'
+			}
+		},
+		required: ["location"]
+	},
+	async (params) => {
+		if (params.location.trim() === '') {
+		  throw new Error('Missing location.');
+			// return { records, response };
+		}
+		const response = {current_weather:'24 C, Cloudy'};
+		return response ;
+	}
+);
+tools.add(
+	'get_date_time', // name
+	'Get the current date and time', // desciption
+	{
+		type: 'object',
+		properties: {
+		}
+	},
+	async (_params) => {
+		const response = {
+			date_time: new Date().toISOString(),
+		}
+		return response ;
+	}
+);
+
+export default tools;

package/module.md

@@ -0,0 +1,189 @@
+# @j-o-r/hello-dave Module Documentation
+
+## Overview
+**Name:** @j-o-r/hello-dave  
+**Version:** 0.0.0  
+**Description:** API to various endpoints mainly focused on AI  
+
+This is a small, ESM-only Node.js toolkit for building AI "agents" with:
+- One unified Prompt abstraction across multiple LLM providers (x.ai Grok, OpenAI, Anthropic)
+- First-class function calling via a simple ToolSet
+- A tiny AgentManager that wires everything together (CLI, direct calls, WS server/client)
+- Optional persisted sessions and records on disk
+
+Key features include:
+- Support for multiple AI providers: x.ai (Grok), OpenAI, Anthropic
+- ToolSet for function calling with JSON schema
+- AgentManager for easy integration
+- CLI tools for interactive use
+- WebSocket-based agent servers and clients for distributed setups
+- Session persistence under ./.cache/hello-dave/<agent-name>/
+- Built-in tools like JavaScript interpreter and bash execution
+
+Note: This is a personal project, created for convenience and exclusively used and tested on Debian/Ubuntu. It can be used to create, use and combine Agents. It has great potential and is very powerful; e.g., `hdCode` has full access to the user environment and is able to execute any command or code. Prompt injection is a risk so use with care.
+
+## Installation Notes
+The module is already installed in the current working directory. For manual installation in your project:
+```bash
+npm install @j-o-r/hello-dave
+```
+
+Requirements:
+- Node.js >= 20 (ESM only)
+- API keys via environment variables (set only what you use):
+  - XAIKEY for x.ai (Grok)
+  - OPENAIKEY for OpenAI
+  - ANTHKEY for Anthropic
+  - BRAVESEARCHKEY for Brave Search tool (optional)
+
+After installation, use either the programmatic API (AgentManager) or the provided CLIs.
+
+For development from repo:
+- npm install
+- export keys
+- node examples/grok.js  # or add ./bin to PATH
+
+## API Usage Examples
+
+### Minimal Direct Call
+```js
+import AgentManager from '@j-o-r/hello-dave';
+
+const agent = new AgentManager({ name: 'grok' });
+agent.setup({
+  prompt: 'Be precise and concise.',
+  api: 'grok',
+  options: {
+    model: 'grok-4',
+    search_parameters: { mode: 'auto' }
+  },
+  toolsetMode: 'auto',
+  contextWindow: 250_000
+});
+
+const answer = await agent.directCall('Two bullet points on tail recursion.');
+console.log(answer);
+```
+
+### Adding Custom Tools
+```js
+const toolset = agent.getToolset();
+if (toolset) {
+  toolset.add(
+    'say_hello',
+    'Return a friendly greeting',
+    {
+      type: 'object',
+      properties: { name: { type: 'string', description: 'Who to greet' } },
+      required: ['name']
+    },
+    async ({ name }) => `Hello, ${name}!`
+  );
+}
+```
+
+### Running as Tool Server
+```js
+agent.enableServer('search', 'General-purpose search interface', 8000);
+// WS on ws://127.0.0.1:8000/ws; connected clients become callable tools.
+```
+
+### Attaching as WS Client
+```js
+agent.attach(
+  'code',
+  'Run JavaScript snippets safely and return output',
+  'ws://127.0.0.1:8000/ws'
+);
+```
+
+### CLI Example (from examples/grok.js)
+- Interactive: node examples/grok.js
+- One-shot: echo "question" | node examples/grok.js
+- With tools: node examples/grok.js --tools javascript,bash
+- Server: node examples/grok.js --serve 8000 --tools javascript,bash
+- Client: node examples/grok.js --connect ws://127.0.0.1:8000/ws
+
+### Utils
+```bash
+npx hdClear  # Clear sessions and logs
+npx hdInspect [file.ndjson]  # Read ndjson files
+npx hdPrompt  # Design prompts (needs x.ai key)
+npx hdAsk  # Ask generic question to GPT (needs OpenAI key)
+npx hdConnect [ws://url]  # Connect to WS agent server
+```
+
+## Full API Reference
+
+### AgentManager (main entry point)
+From types/AgentManager.d.ts
+
+**Constructor:**
+- `new AgentManager(options: Options)`: Create agent with name and optional cachePath.
+
+**Methods:**
+- `setup(setup: Setup): this`: Configure prompt, api, options, etc.
+- `startCli(description: string): void`: Start CLI for local usage.
+- `attach(name: string, description: string, url?: string): AgentClient`: Attach to WS server as client.
+- `enableServer(name: string, description?: string, port?: number): void`: Start WS server on localhost.
+- `directCall(input: string): Promise<string>`: Direct call to the prompt.
+- `getPrompt(): Prompt`: Get the Prompt instance.
+- `getToolset(): ToolSet | void`: Get the ToolSet if enabled.
+- `environment(): Promise<EnvironmentInfo>`: Get environment info.
+- `addGenericToolcall(name: string): void`: Add a generic tool call.
+
+**Types:**
+- `Options`: { name: string, cachePath?: string }
+- `Setup`: { prompt: string, options: OAOptions | XOptions | ANTHOptions, api: 'gpt' | 'grok' | 'claude', contextWindow?: number, toolsetMode?: 'auto' | 'required' | void, debug?: boolean }
+
+### ToolSet
+From types/ToolSet.d.ts
+
+**Constructor:**
+- `new ToolSet(choice?: string)`: 'auto' | 'none' | 'required'
+
+**Properties:**
+- `length: number`: Number of registered functions.
+- `toolChoice: string`
+
+**Methods:**
+- `add(name: string, description: string, parameters: TSSchema, method: (arg0: object) => Promise<any>): void`: Register a tool.
+- `get(name: string): TSTool`: Get a tool.
+- `delete(name: string): void`: Remove a tool.
+- `has(name: string): boolean`: Check if tool exists.
+- `list(): TSToolListItem[]`: List all tools.
+- `call(name: string, params: object): Promise<any>`: Execute a tool.
+- `execute(prompt: Prompt): Promise<void>`: Execute tool calls from prompt.
+
+**Types:**
+- `TSSchema`: { type: string, properties: object, required?: string[] }
+- `TSTool`: { description: string, parameters: TSSchema, method: (arg0: object) => Promise<any> }
+- `TSToolListItem`: { name: string, description: string, parameters: TSSchema }
+
+### Prompt
+From types/Prompt.d.ts (partial, large file)
+
+Handles uniform message format, function-call plumbing, truncation, provider-neutral calls.
+
+### Other Classes
+- `AgentClient`: WS client for processing requests.
+- `AgentServer`: WS server that turns clients into ToolSet functions.
+- `Cli`: TUI with history, shortcuts (uses @j-o-r/cli internally).
+- `Session`: On-disk persistence for sessions, logs, records.
+
+### API Adaptors
+- API/x.ai: For Grok
+- API/openai.com: For GPT
+- API/anthropic.com: For Claude
+- API/brave.com: For search tool
+
+## Dependencies
+- **@j-o-r/apiserver**: ^2.1.5 - For HTTP/WS server functionality (see its module.md for details).
+- **@j-o-r/cli**: * - For CLI interface (interactive TUI with modes, questions, shortcuts).
+- **gpt-3-encoder**: * - For token encoding.
+
+Relevant dependency info:
+- @j-o-r/cli: Interactive CLI framework with mode-based output, command parsing, key mappings, spinners. Used for the built-in CLI tools.
+- @j-o-r/apiserver: Lightweight HTTP/WS server for API controllers, streaming, file serving. Used for WS agent servers.
+
+All dependencies are scoped under @j-o-r, personal modules.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@j-o-r/hello-dave",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "ESM toolkit for building AI agents with unified access to Grok, OpenAI, and Anthropic endpoints",
+  "main": "lib/AgentManager.js",
+  "types": "types/AgentManager.d.ts",
+  "bin": {
+    "hdPrompt": "bin/hdPrompt.js",
+    "hdNpm": "bin/hdNpm.js",
+    "hdAsk": "bin/hdAsk.js",
+    "hdCode": "bin/hdCode.js",
+    "hdConnect": "bin/hdConnect.js",
+    "hdInspect": "bin/hdInspect.js",
+    "hdClear": "bin/hdClear.js"
+  },
+  "scripts": {
+    "hdPrompt": "bin/hdPrompt.js",
+    "hdAsk": "bin/hdAsk.js",
+    "hdCode": "bin/hdCode.js",
+    "hdNpm": "bin/hdNpm.js",
+    "hdConnect": "bin/hdConnect.js",
+    "hdInspect": "bin/hdInspect.js",
+    "hdClear": "bin/hdClear.js",
+    "test": "scenarios/grok.js",
+    "release": "npm run types && npm pack --pack-destination=release",
+    "types": "rm -fr types/* && tsc -p tsc.json",
+    "publish": "npm run release && npm publish --access public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/duin/hello-dave"
+  },
+  "dependencies": {
+    "@j-o-r/apiserver": "^2.1.5",
+    "@j-o-r/cli": "*",
+    "gpt-3-encoder": "*"
+  },
+  "author": "Jorrit Duin <j-o-r@duin.work>",
+  "bugs": {
+    "url": "https://codeberg.org/duin/hello-dave/issues"
+  },
+  "license": "Apache-2.0",
+  "keywords": [],
+  "homepage": "https://codeberg.org/duin",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/types/API/anthropic.com/text.d.ts

@@ -0,0 +1,207 @@
+export type Prompt = import("../../Prompt.js").default;
+export type ToolSet = import("../../ToolSet.js").default;
+/**
+ * Search-tool configuration options.
+ */
+export type SearchOptions = {
+    /**
+     * Engine identifier (constant).
+     */
+    type: "web_search_20250305";
+    /**
+     * Human-readable tool name.
+     */
+    name: "web_search";
+    /**
+     * Maximum searches the caller may perform in a single request.
+     */
+    max_uses?: number | undefined;
+    /**
+     * Domains that are explicitly allowed in the results.
+     */
+    allowed_domains?: string[] | undefined;
+    /**
+     * Domains that must never appear in the results.
+     */
+    blocked_domains?: string[] | undefined;
+    /**
+     * Hints for localizing search results.
+     */
+    user_location?: UserLocation | undefined;
+};
+/**
+ * Geographic context supplied to the search tool.
+ */
+export type UserLocation = {
+    /**
+     * How exact the location is.
+     */
+    type: "approximate" | "precise";
+    /**
+     * City name (e.g., "San Francisco").
+     */
+    city: string;
+    /**
+     * First-level region or state (e.g., "California").
+     */
+    region: string;
+    /**
+     * ISO-3166-1 alpha-2 country code (e.g., "US").
+     */
+    country: string;
+    /**
+     * IANA time-zone identifier (e.g., "America/Los_Angeles").
+     */
+    timezone: string;
+};
+export type ANTHContent = {
+    /**
+     * - The type of content.
+     */
+    type: string;
+    /**
+     * - The text content.
+     */
+    text: string;
+};
+export type ANTHOptions = {
+    /**
+     * - What model to use
+     */
+    model?: string | undefined;
+    /**
+     * - System prompt
+     */
+    system?: string | undefined;
+    /**
+     * - Prompt / conversation
+     */
+    messages?: ANTHContent[] | undefined;
+    /**
+     * - Prompt / conversation
+     */
+    tools?: (ANTHTool | SearchOptions)[] | undefined;
+    /**
+     * - ..
+     */
+    tool_choice?: ANTHToolChoice | undefined;
+    /**
+     * - ..
+     */
+    metadata?: object | undefined;
+    /**
+     * -  What sampling temperature to use, between 0 and 2.
+     */
+    temperature?: number | undefined;
+    /**
+     * -  The maximum number of tokens allowed for the generated answer.
+     */
+    max_tokens?: number | undefined;
+    /**
+     * -  Number between > 0  0.1 is NO top_p
+     */
+    top_p?: number | undefined;
+    /**
+     * -  Number between > 0  < 2048
+     */
+    top_k?: number | undefined;
+    /**
+     * - embedded search
+     */
+    search?: SearchOptions | undefined;
+    /**
+     * - Chunk/stream request default null
+     */
+    stream?: boolean | undefined;
+    /**
+     * - Reasoning
+     */
+    thinking?: {
+        /**
+         * -
+         */
+        type?: "enabled" | undefined;
+        /**
+         * -
+         */
+        budget_tokens?: number | undefined;
+    } | undefined;
+};
+export type ANTHRequest = {
+    body: ANTHOptions;
+    headers: Headers;
+    /**
+     * -
+     */
+    url: string;
+};
+export type ANTHTool = {
+    /**
+     * - The name of the tool.
+     */
+    name: string;
+    /**
+     * - A brief description of the tool's functionality.
+     */
+    description: string;
+    /**
+     * - The JSON schema defining the input parameters for the tool.
+     */
+    input_schema: Object;
+};
+/**
+ * Represents a tool usage event.
+ */
+export type ANTHToolUse = {
+    /**
+     * - The type of the tool usage event, in this case "tool_use".
+     */
+    type: string;
+    /**
+     * - The unique identifier for the tool usage event.
+     */
+    id: string;
+    /**
+     * - The name of the tool used.
+     */
+    name: string;
+    /**
+     * - The input data for the tool usage.
+     */
+    input: Object;
+};
+export type ANTHToolChoice = {
+    /**
+     * -
+     */
+    type: string;
+};
+/**
+* Create an anthropic request
+* @param {Prompt} prompt
+* @param {ToolSet} [tools]
+* @param {ANTHOptions} [opts] overwrite default request settings
+* @param {Headers|object} [hdrs] - optional headers to pass
+* @returns {ANTHRequest}
+* @throws {Error}
+*/
+export function generateRequest(prompt: Prompt, tools?: ToolSet, opts?: ANTHOptions, hdrs?: Headers | object): ANTHRequest;
+/**
+* Process an openai response
+* @param {number} duration - the time is MS before and after the request
+* @param {import('lib/request.js').FetchResponse} res
+* @param {Prompt} prompt
+* @param {ToolSet} [toolset]
+* @returns {Promise<void>}
+* @throws {Error}
+*/
+export function parseResponse(duration: number, prompt: Prompt, res: any, toolset?: ToolSet): Promise<void>;
+/**
+* Do a request
+* @param {Prompt} prompt
+* @param {ToolSet|null} toolset
+* @param {ANTHOptions} [options]:
+* @param {number} [counter] - leave empty this counts the number of requests when doing recursive request calls
+* @return {Promise<import('../../Session.js').Message>}
+*/
+export function request(prompt: Prompt, toolset?: ToolSet | null, options?: ANTHOptions, counter?: number): Promise<import("../../Session.js").Message>;