@j-o-r/hello-dave 0.0.10 → 0.1.1

package/types/API/x.ai/image.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Generates one or more images from a text prompt using Grok Imagine.
+ *
+ * @async
+ * @function generateImage
+ * @param {string} prompt - Detailed text prompt describing the desired image.
+ * @param {Object} [options={}] - Optional generation parameters.
+ * @param {string} [options.model='grok-imagine-image-quality'] - Model to use.
+ * @param {number} [options.n=1] - Number of images to generate (1–10).
+ * @param {string} [options.response_format='url'] - `'url'` or `'b64_json'`.
+ * @returns {Promise<Object>} Result containing `local_path`, `url` (or `base64`), and metadata.
+ * @throws {Error} On missing prompt or API errors.
+ *
+ * @example
+ * const result = await generateImage("A futuristic city at night");
+ * console.log(result.local_path);
+ */
+export function generateImage(prompt: string, options?: {
+    model?: string | undefined;
+    n?: number | undefined;
+    response_format?: string | undefined;
+}): Promise<Object>;
+/**
+ * Edits one or more images using a natural language prompt.
+ * Supports up to 3 reference images for compositing, style transfer, or multi-subject scenes.
+ *
+ * @async
+ * @function editImage
+ * @param {string} prompt - Description of the desired edit.
+ * @param {string|Buffer|Blob|Array<string|Buffer|Blob>} imageInputs - One or more images (URL, path, base64, Buffer, or Blob).
+ * @param {Object} [options={}] - Optional parameters.
+ * @param {string} [options.model='grok-imagine-image-quality']
+ * @param {number} [options.n=1]
+ * @param {string} [options.response_format='url']
+ * @returns {Promise<Object>} Result with edited image.
+ * @throws {Error} If more than 3 images are provided or on API error.
+ *
+ * @example
+ * // Single image edit
+ * const result = await editImage("Make this a pencil sketch", "./photo.png");
+ *
+ * @example
+ * // Multi-image editing (up to 3)
+ * const result = await editImage(
+ *   "Combine these two people into one scene",
+ *   ["./person1.png", "./person2.png"]
+ * );
+ */
+export function editImage(prompt: string, imageInputs: string | Buffer | Blob | Array<string | Buffer | Blob>, options?: {
+    model?: string | undefined;
+    n?: number | undefined;
+    response_format?: string | undefined;
+}): Promise<Object>;
+/**
+ * Generates a video from a still image and text prompt.
+ * This function is fully automatic — it submits the request and polls internally
+ * until the video is ready before returning.
+ *
+ * @async
+ * @function generateVideo
+ * @param {string} prompt - Description of the desired motion or animation.
+ * @param {string|Buffer|Blob} imageInput - Source image (URL, path, base64, Buffer, or Blob).
+ * @param {Object} [options={}] - Optional video parameters.
+ * @param {number} [options.duration=8] - Video duration in seconds.
+ * @param {string} [options.aspect_ratio='16:9'] - Aspect ratio.
+ * @param {string} [options.resolution='720p'] - Output resolution.
+ * @returns {Promise<Object>} Result containing `local_path` and `url` of the generated video.
+ * @throws {Error} On missing inputs or generation failure.
+ *
+ * @example
+ * const result = await generateVideo(
+ *   "Make the water crash down and slowly pan out",
+ *   "https://example.com/waterfall.png",
+ *   { duration: 12 }
+ * );
+ * console.log(result.local_path);
+ */
+export function generateVideo(prompt: string, imageInput: string | Buffer | Blob, options?: {
+    duration?: number | undefined;
+    aspect_ratio?: string | undefined;
+    resolution?: string | undefined;
+}): Promise<Object>;

package/types/API/x.ai/index.d.ts

@@ -0,0 +1,7 @@
+declare namespace _default {
+    export { image };
+    export { imageToolset };
+}
+export default _default;
+import * as image from './image.js';
+import imageToolset from './ImageToolset.js';

package/types/AgentManager.d.ts

@@ -75,7 +75,7 @@ declare class AgentManager {
     /** @returns {Promise<import('./fafs.js').EnvironmentInfo>} System env info. */
     environment(): Promise<any> & lt;
     /**
-     * Adds a pre-defined generic tool from toolsPool to this agent's ToolSet.
+     * Adds a pre-defined generic tool from toolsPool (genericToolset) 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');

package/types/CdnToolset.d.ts

@@ -0,0 +1,20 @@
+export default tools;
+/**
+ * @module lib/CdnToolset
+ * Dedicated ToolSet for CDN / remote public file publishing.
+ *
+ * Contains only the tools related to publishing files to a remote web server
+ * via SSH/SCP (defined by SSH_EP environment variable).
+ *
+ * This allows clean separation: generic tools + CDN tools + domain-specific toolsets.
+ *
+ * Usage:
+ *   import cdnTools from './CdnToolset.js';
+ *   myToolset.borrow(cdnTools);
+ *
+ * Or use directly:
+ *   import cdnTools from './CdnToolset.js';
+ *   await cdnTools.call('listProjects');
+ */
+declare const tools: ToolSet;
+import { ToolSet } from './index.js';

package/types/ToolSet.d.ts

@@ -88,6 +88,14 @@ declare class ToolSet {
      * @returns {TSToolListItem[]} Array of tool summaries, sorted by name
      */
     list(): TSToolListItem[];
+    /**
+     * Borrows/copies all registered tools (function_calls) from another ToolSet into this one.
+     * Overwrites if a tool with the same name already exists in this ToolSet.
+     * Uses only public API for compatibility.
+     * @param {ToolSet} sourceToolSet - The ToolSet instance to borrow tools from (e.g. musicToolset)
+     * @returns {ToolSet} Returns this instance to allow chaining
+     */
+    borrow(sourceToolSet: ToolSet): ToolSet;
     /**
      * Getter for the current tool choice setting.
      * @returns {string} The tool choice: 'auto', 'none', or 'required'

package/types/cdn.d.ts

@@ -0,0 +1,141 @@
+declare namespace _default {
+    export { getSshConfig };
+    export { ensureRemoteDir };
+    export { ensureProjectStructure };
+    export { listProjects };
+    export { deleteProject };
+    export { publishFile };
+    export { publishToProject };
+}
+export default _default;
+/**
+ * Parse and validate the SSH_EP environment variable.
+ *
+ * Supports both `ssh://user@host:port` and `user@host:port` formats.
+ *
+ * @returns {{user: string, host: string, port: number, raw: string}}
+ *          Parsed SSH connection details.
+ *
+ * @throws {Error} If SSH_EP is missing or has an invalid format.
+ *
+ * @example
+ * // Required environment variable:
+ * // export SSH_EP='ssh://jorrit@drive.duin.xyz:4301'
+ */
+export function getSshConfig(): {
+    user: string;
+    host: string;
+    port: number;
+    raw: string;
+};
+/**
+ * Ensure a remote directory exists under `htdocs/`.
+ * Creates all parent directories as needed (`mkdir -p`).
+ *
+ * @param {string} remoteRelativeDir - Relative path under htdocs (e.g. "tmp/cdn-demo-123" or "projects/my-project")
+ * @returns {Promise<string>} The full remote directory path (e.g. "htdocs/tmp/cdn-demo-123")
+ */
+export function ensureRemoteDir(remoteRelativeDir: string): Promise<string>;
+/**
+ * Ensure the remote project directory structure exists.
+ * Creates `htdocs/projects/<slug>` (and the `generated` subfolder).
+ *
+ * @param {string} projectSlug - Project identifier (will be sanitized)
+ * @returns {Promise<string>} The remote directory path under htdocs
+ */
+export function ensureProjectStructure(projectSlug: string): Promise<string>;
+/**
+ * List all existing projects on the remote server.
+ *
+ * Scans the `htdocs/projects/` directory and returns metadata for each project.
+ * Useful when starting without prior context about what has already been published.
+ *
+ * @returns {Promise<Array<{slug: string, url: string, fileCount: number, created?: string}>>}
+ *          Array of project objects.
+ *
+ * @throws {Error} If the SSH connection or directory listing fails.
+ *
+ * @example
+ * const projects = await cdn.listProjects();
+ * console.log(projects[0].url); // https://drive.duin.xyz/projects/my-project/
+ */
+export function listProjects(): Promise<Array<{
+    slug: string;
+    url: string;
+    fileCount: number;
+    created?: string;
+}>>;
+/**
+ * Delete an entire project folder from the remote server.
+ *
+ * Permanently removes `htdocs/projects/<slug>` and all its contents.
+ * Use with caution — this operation cannot be undone.
+ *
+ * @param {string} projectSlug - Project identifier (will be sanitized to kebab-case)
+ * @returns {Promise<{deleted: boolean, project: string}>}
+ *
+ * @example
+ * await cdn.deleteProject('my-old-project');
+ */
+export function deleteProject(projectSlug: string): Promise<{
+    deleted: boolean;
+    project: string;
+}>;
+/**
+ * Publish a single local file to an arbitrary location on the public CDN.
+ *
+ * Automatically creates any missing parent directories.
+ * Returns a direct public HTTPS URL.
+ *
+ * @param {string} localPath - Absolute or relative path to the local file
+ * @param {string} remoteRelativePath - Target path under htdocs (e.g. "tmp/audio-123.mp3" or "projects/my-project/reference.wav")
+ *
+ * @returns {Promise<{public_url: string, remote_path: string}>}
+ *
+ * @example
+ * const result = await cdn.publishFile(
+ *   '/tmp/generated.mp3',
+ *   'tmp/quick-reference.mp3'
+ * );
+ * console.log(result.public_url);
+ */
+export function publishFile(localPath: string, remoteRelativePath: string): Promise<{
+    public_url: string;
+    remote_path: string;
+}>;
+/**
+ * Publish one or more local files into an organized project folder on the public CDN.
+ *
+ * Supports both single file (string) and multiple files (array).
+ * Automatically creates the project directory and generates `meta.json`.
+ * Optional `description.md` and `plan.md` files can be created.
+ *
+ * @param {string|string[]} localPaths - Single path or array of local file paths
+ * @param {string} projectSlug - Project identifier (sanitized to kebab-case)
+ * @param {Object} [options]
+ * @param {string} [options.description] - Human-readable project description
+ * @param {string} [options.plan] - Planning notes or step-by-step evolution
+ * @param {string} [options.filename] - Custom filename (only used when uploading a single file)
+ *
+ * @returns {Promise<{public_urls: string[], project_folder: string, meta: object}>}
+ *
+ * @example
+ * // Multiple files
+ * const result = await cdn.publishToProject(
+ *   ['audio.mp3', 'cover.jpg'],
+ *   'my-project',
+ *   { description: 'Music cover project' }
+ * );
+ *
+ * // Single file with custom name
+ * await cdn.publishToProject('/tmp/file.mp3', 'my-project', { filename: 'final.mp3' });
+ */
+export function publishToProject(localPaths: string | string[], projectSlug: string, options?: {
+    description?: string | undefined;
+    plan?: string | undefined;
+    filename?: string | undefined;
+}): Promise<{
+    public_urls: string[];
+    project_folder: string;
+    meta: object;
+}>;

package/types/index.d.ts

@@ -1,3 +1,4 @@
+export { default as CdnToolset } from "./CdnToolset.js";
 import AgentManager from './AgentManager.js';
 import AgentServer from './AgentServer.js';
 import AgentClient from './AgentClient.js';
@@ -5,14 +6,17 @@ import Prompt from './Prompt.js';
 import ToolSet from './ToolSet.js';
 import Session from './Session.js';
 export namespace API {
-    namespace text {
+    export namespace text {
         export { gpt };
         export { xai };
         export { claude };
     }
-    namespace search {
+    export namespace search {
         export { brave };
     }
+    export { minimax };
+    export { stability };
+    export { xaitools };
 }
 import Cli from './Cli.js';
 import { env } from './fafs.js';
@@ -23,4 +27,7 @@ import { request as gpt } from './API/openai.com/reponses/text.js';
 import { request as xai } from './API/x.ai/responses.js';
 import { request as claude } from './API/anthropic.com/text.js';
 import { request as brave } from './API/brave.com/search.js';
+import minimax from './API/minimax/index.js';
+import stability from './API/stability.ai/index.js';
+import xaitools from './API/x.ai/index.js';
 export { AgentManager, AgentServer, AgentClient, Prompt, ToolSet, Session, Cli, env, GLOBAL, wsCli, wsIO };

package/docs/multi-agent-clusters.md.bak

@@ -1,229 +0,0 @@
-# Multi-Agent Clusters in Dave: v0.0.9
-
-Welcome to the exciting world of **Multi-Agent Clusters** in the Dave framework! 🚀 If you're ready to scale your AI agents into powerful, collaborative clusters, you've come to the right place. This guide walks you through setting up CodeServer with PM2, spawning agents, launching in server mode, connecting clients, querying sessions, managing with PM2, testing, and more. By the end, you'll have a robust cluster humming along, enabling self-aware, interconnected agents. Let's dive in step-by-step!
-
-## CodeServer PM2 Setup
-
-CodeServer is the backbone of your multi-agent cluster, providing a WebSocket-based server for agent communication. It integrates seamlessly with PM2 for process management, ensuring high availability and easy scaling.
-
-### Prerequisites
-- Node.js (v18+ recommended)
-- PM2 installed globally: `npm install -g pm2`
-- Dave project cloned and dependencies installed: `npm install`
-
-### Step-by-Step Setup
-1. **Choose Your Launch Method**:
-   - Use the binary script: `./bin/codeDave` (convenient for quick starts).
-   - Or the shell script: `./agents/codeserver.sh` (for more customization).
-
-2. **Default Configuration**:
-   - **Port**: 9000 (change with `--port 8080` if needed).
-   - **Secret**: "123" (for secure WebSocket connections; override with `--secret your_secret`).
-
-3. **Launch CodeServer with PM2**:
-   Run the following to start CodeServer as a PM2-managed process:
-   ```
-   pm2 start ./bin/codeDave --name "hello-dave_code_9000" -- --serve --port 9000 --secret 123
-   ```
-   - `--serve`: Enables server mode (detailed below).
-   - This creates a process named `hello-dave_code_9000` for easy identification.
-
-4. **Verify Setup**:
-   - Check PM2 status: `pm2 list` (look for `hello-dave_code_9000` in "online" status).
-   - Test connection: Use a WebSocket client to connect to `ws://127.0.0.1:9000/ws` with secret "123".
-
-## Creating Agents via spawn_agent
-
-Spawning agents is where the magic happens! Use the `spawn_agent` function to dynamically create and integrate new agents into your cluster.
-
-### Reference to spawn_agent Blueprint
-For a deep dive into `spawn_agent`, check the [spawn_agent blueprint](../blueprints/spawn-agent.md) (or implement based on the core Dave agent manager patterns in [agent-manager.md](./agent-manager.md)).
-
-### Step-by-Step Agent Creation
-1. **Import and Initialize**:
-   In your Node.js script:
-   ```javascript
-   const { spawn_agent } = require('./agents/spawn'); // Adjust path as needed
-   ```
-
-2. **Spawn an Agent**:
-   ```javascript
-   const newAgent = spawn_agent({
-     name: "weatherPredictor",
-     prompt: "You are a weather prediction agent. Use tools to fetch data.",
-     tools: ['web_search', 'weather_api'],
-     cluster: "ws://127.0.0.1:9000/ws" // Attach to your CodeServer
-   });
-   ```
-   - This generates the agent and attaches it to the cluster for collaborative querying.
-
-3. **Integration with Cluster**:
-   - Agents auto-register with CodeServer upon spawn.
-   - Use `newAgent.connect({ secret: "123" })` to ensure secure attachment.
-
-## Launching Server Mode (--serve)
-
-Server mode turns CodeServer into a persistent hub for multi-agent interactions.
-
-1. **Command**:
-   ```
-   ./bin/codeDave --serve --port 9000 --secret 123
-   ```
-
-2. **What Happens**:
-   - Listens on WebSocket endpoint `/ws`.
-   - Handles agent registrations and session management.
-   - Supports multiple concurrent clients.
-
-3. **PM2 Integration**:
-   As shown in setup, wrap it in PM2 for daemonization and auto-restart.
-
-## Attaching Clients (--connect)
-
-Clients (like other Dave instances or tools) connect to the cluster for tool calls and session sharing.
-
-1. **Basic Connection**:
-   ```
-   ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123
-   ```
-   - This attaches the client as a tool-calling endpoint.
-   - Use in scripts for agent-to-agent communication.
-
-2. **Advanced Usage**:
-   - Pipe inputs: `echo "query" | ./bin/dave.js --connect ...`
-   - Handle toolcalls: Clients receive and execute tools on behalf of the cluster.
-
-## Querying via bin/dave.js --connect
-
-For one-shot queries or building sessions, use `bin/dave.js` with connection flags.
-
-### One-Shot Example
-Predict weather with a quick query:
-```
-echo "predict weather in NYC" | ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123
-```
-- Builds a temporary session, routes to relevant agents (e.g., weatherPredictor), and returns results.
-
-### Session Building
-For persistent sessions:
-```
-./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123 --session my_weather_session
-```
-- Follow with queries to maintain state across interactions.
-
-## PM2 Start/Stop/Reload
-
-PM2 makes cluster management a breeze!
-
-1. **List Processes**:
-   ```
-   pm2 list
-   ```
-   - Shows status of `hello-dave_code_9000` and other agents.
-
-2. **Start/Stop**:
-   ```
-   pm2 start hello-dave_code_9000  # Start
-   pm2 stop hello-dave_code_9000   # Stop
-   pm2 restart hello-dave_code_9000 # Restart
-   ```
-
-3. **Reload (Zero-Downtime)**:
-   ```
-   pm2 reload hello-dave_code_9000
-   ```
-   - Ideal for updates without interrupting sessions.
-
-4. **Logs and Monitoring**:
-   ```
-   pm2 logs hello-dave_code_9000
-   pm2 monit
-   ```
-
-## Testing One-Shots and Sessions
-
-Ensure your cluster is rock-solid with these tests.
-
-### One-Shot Testing
-1. Spawn a test agent.
-2. Run: `echo "test query" | ./bin/dave.js --connect ...`
-3. Verify output matches expected (e.g., no errors, relevant response).
-
-### Session Testing
-1. Start a session: `./bin/dave.js --connect ... --session test`
-2. Send multiple queries: `echo "first" | ...` then `echo "follow-up" | ...`
-3. Check session persistence (e.g., context retained).
-
-### End-to-End Test Script
-```bash
-#!/bin/bash
-# test_cluster.sh
-pm2 start ./bin/codeDave --name "test_code" -- --serve --port 9000 --secret 123
-sleep 2
-echo "Hello cluster!" | ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123
-pm2 stop test_code
-```
-
-## Self-Awareness: Detecting PM2/CodeServer in Prompts
-
-Make your agents smarter by embedding cluster awareness!
-
-- **In Agent Prompts**:
-  Include detection logic: "If running under PM2/CodeServer (detect via env vars like PM2_PROCESS_ID or connection to ws://localhost:9000), coordinate with cluster agents."
-
-- **Implementation**:
-  Agents auto-detect via:
-  ```javascript
-  if (process.env.PM2_PROCESS_ID || connection.url.includes('9000')) {
-    // Cluster mode: Share context
-  }
-  ```
-  This enables self-aware routing, e.g., "Delegate weather query to weatherPredictor in cluster."
-
-## Mermaid Diagram: Cluster Architecture
-
-Visualize your setup!
-
-```mermaid
-graph TD
-    A[PM2 Manager] --> B[CodeServer<br/>Port 9000 /ws]
-    B --> C[Agent 1<br/>spawn_agent()]
-    B --> D[Agent 2<br/>e.g., WeatherPredictor]
-    E[Client / bin/dave.js] -->|connect| B
-    E -->|one-shot| F[Session Builder]
-    G[Tools: web_search, etc.] <-->|toolcalls| C
-    G <-->|toolcalls| D
-    style B fill:#f9f,stroke:#333,stroke-width:2px
-```
-
-- **Nodes**: PM2 oversees CodeServer, which hubs agents and clients.
-- **Flows**: Connections for spawning, querying, and tool execution.
-
-## Examples
-
-### Full Cluster Spawn and Query
-1. Start CodeServer: `pm2 start ./bin/codeDave --name code_9000 -- --serve --port 9000 --secret 123`
-2. Spawn Agent (in Node script):
-   ```javascript
-   const agent = spawn_agent({ name: &quot;queryMaster&quot;, cluster: &quot;ws://127.0.0.1:9000/ws&quot; });
-   ```
-3. Query: `echo &quot;What&apos;s the plan?&quot; | ./bin/dave.js --connect ws://127.0.0.1:9000/ws --secret 123`
-
-### Multi-Agent Collaboration
-- Spawn multiple: weather, news, summary agents.
-- Query: &quot;Summarize today&apos;s news and weather&quot; → Routes to respective agents via cluster.
-
-## Troubleshooting
-
-- **Connection Refused**: Ensure CodeServer is running (`pm2 list`) and port 9000 is free (`lsof -i :9000`).
-- **Secret Mismatch**: Double-check `--secret` flags match.
-- **PM2 Crashes**: View logs (`pm2 logs`)—common issues: missing deps or port conflicts. Restart: `pm2 restart all`.
-- **Agent Not Attaching**: Verify `spawn_agent` cluster URL and secret. Test WebSocket manually.
-- **Session Loss**: Check PM2 memory limits (`pm2 desc code_9000`); increase if needed.
-- **One-Shot Fails**: Ensure input is piped correctly; debug with `--verbose`.
-
-If issues persist, reference [project-overview.md](./project-overview.md) or spawn a debug agent!
-
----
-
-*Ready for v0.0.9 deployment! Cluster up and conquer those multi-agent challenges. 🎉 Questions? Ping the Dave community.*