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

package/lib/API/x.ai/image.to.video.md

@@ -0,0 +1,23 @@
+#### Model Capabilities
+
+# Image-to-Video
+
+Transform a still image into a video by providing a source image along with your prompt. The model animates the image content based on your instructions.
+
+You can provide the source image as:
+
+* A **public URL** pointing to an image
+* A **base64-encoded data URI** (e.g., `data:image/jpeg;base64,...`)
+
+The demo below shows this in action; hold to animate a still image:
+
+In the Vercel AI SDK, the `prompt` parameter accepts an object with `image` and `text` fields for image-to-video generation. The `image` field can be a URL string, base64-encoded string, `Uint8Array`, `ArrayBuffer`, or `Buffer`.
+
+## Related
+
+* [Video Generation](/developers/model-capabilities/video/generation) — Generate videos from text prompts
+* [Reference-to-Video](/developers/model-capabilities/video/reference-to-video) — Guide a video with reference images
+* [Video Editing](/developers/model-capabilities/video/editing) — Edit existing videos
+* [API Reference](/developers/rest-api-reference) — Full endpoint documentation
+* [Imagine API Landing Page](https://x.ai/api/imagine) — Showcase of the Imagine API in action
+

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

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

package/lib/AgentManager.js

@@ -183,7 +183,7 @@ class AgentManager {
   }
 
   /**
-   * 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/lib/CdnToolset.js

@@ -0,0 +1,191 @@
+import { ToolSet } from './index.js';
+import cdn from './cdn.js';
+
+/**
+ * @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');
+ */
+
+const tools = new ToolSet('auto');
+
+/**
+ * Single source of truth for cleaning over-escaped strings from LLMs.
+ * (Duplicated here for self-containment of the CDN toolset)
+ */
+const guessOverEscaping = (s) => {
+	if (typeof s !== 'string') return s;
+
+	let current = s.trim();
+	const seen = new Set();
+	let iterations = 0;
+	const MAX_ITER = 6;
+
+	while (iterations < MAX_ITER && !seen.has(current)) {
+		seen.add(current);
+		iterations++;
+
+		try {
+			const parsed = JSON.parse(current);
+			if (typeof parsed === 'string') {
+				current = parsed;
+				continue;
+			}
+		} catch (e) { }
+
+		if (current.startsWith('\\"') && current.endsWith('\\"')) {
+			current = current.slice(2, -2);
+			continue;
+		}
+
+		if (current.startsWith('"') && current.endsWith('"') && current.length > 2) {
+			const inner = current.slice(1, -1).trim();
+			if (!inner.startsWith('{') && !inner.startsWith('[')) {
+				current = inner;
+				continue;
+			}
+		}
+
+		if (!current.includes('\n') && (current.match(/\\"/g) || []).length >= 1) {
+			const lessEscaped = current.replace(/\\"/g, '"');
+			if (lessEscaped !== current) {
+				current = lessEscaped;
+				continue;
+			}
+		}
+
+		break;
+	}
+
+	return current;
+};
+
+/**
+ * ============================================================================
+ * CDN / PUBLIC FILE EXPOSURE TOOLS
+ * ============================================================================
+ *
+ * Purpose:
+ *   Make local files (generated audio, images, references, outputs from
+ *   lib/API/minimax/music.js, etc.) publicly accessible via HTTPS.
+ *
+ *   This allows remote AI/LLM services to inspect, reference, or use the
+ *   files as input for further generation.
+ *
+ * Underlying module:
+ *   All functionality is provided by lib/cdn.js (SSH/SCP based publishing
+ *   to a remote web server defined by the SSH_EP environment variable).
+ *
+ * Logical workflow for LLMs:
+ *   1. listProjects()      → Discover what already exists
+ *   2. publishFile()       → Quick single-file exposure
+ *   3. publishToProject()  → Organize one or multiple files into a project
+ *   4. deleteProject()     → Clean up when no longer needed
+ *
+ * Requirements:
+ *   - SSH_EP environment variable must be set
+ *   - Remote host serves the 'htdocs' folder publicly over HTTPS
+ */
+
+tools.add(
+	'list_projects',
+	'List all existing projects published on the remote public server.\n' +
+	'Returns slug, public URL, file count, and creation date for each project.\n' +
+	'Use this first when you have no prior context about what has already been published.',
+	{ type: 'object', properties: {} },
+	async () => {
+		return await cdn.listProjects();
+	}
+);
+
+tools.add(
+	'publish_file',
+	'Publish a single local file to a public HTTPS URL via SSH.\n' +
+	'Automatically creates any missing parent directories.\n' +
+	'Best for quick one-off references or when you only need a direct link to one file.',
+	{
+		type: 'object',
+		properties: {
+			localPath: { type: 'string', description: 'Path to the local file to publish' },
+			remoteRelativePath: { type: 'string', description: 'Target path under htdocs (e.g. "tmp/reference.mp3" or "projects/my-project/audio.wav")' }
+		},
+		required: ['localPath', 'remoteRelativePath']
+	},
+	async (params) => {
+		let local = guessOverEscaping(params.localPath).trim();
+		let remote = guessOverEscaping(params.remoteRelativePath).trim();
+		return await cdn.publishFile(local, remote);
+	}
+);
+
+tools.add(
+	'publish_to_project',
+	'Publish one or multiple local files into a structured public project folder.\n' +
+	'Creates the project directory, uploads all files, and generates meta.json.\n' +
+	'Optional description.md and plan.md can be added for context.\n' +
+	'Returns an array of public URLs plus the project folder URL.\n' +
+	'Recommended when you want to keep related files together for remote AI inspection.',
+	{
+		type: 'object',
+		properties: {
+			localPaths: {
+				oneOf: [
+					{ type: 'string', description: 'Single file path' },
+					{ type: 'array', items: { type: 'string' }, description: 'Array of file paths' }
+				]
+			},
+			projectSlug: { type: 'string', description: 'Project folder name (will be sanitized to kebab-case)' },
+			options: {
+				type: 'object',
+				properties: {
+					description: { type: 'string', description: 'Human-readable description of the project' },
+					plan: { type: 'string', description: 'Planning notes or step-by-step evolution' },
+					filename: { type: 'string', description: 'Custom filename (only used for single-file uploads)' }
+				}
+			}
+		},
+		required: ['localPaths', 'projectSlug']
+	},
+	async (params) => {
+		let localPaths = guessOverEscaping(params.localPaths);
+		if (typeof localPaths === 'string') localPaths = [localPaths];
+
+		let projectSlug = guessOverEscaping(params.projectSlug).trim();
+		let options = params.options || {};
+		if (typeof options === 'string') options = JSON.parse(guessOverEscaping(options));
+
+		return await cdn.publishToProject(localPaths, projectSlug, options);
+	}
+);
+
+tools.add(
+	'delete_project',
+	'Permanently delete an entire project folder from the remote public server.\n' +
+	'Removes the project and all its files.\n' +
+	'Use this to clean up temporary or obsolete projects.',
+	{
+		type: 'object',
+		properties: {
+			projectSlug: { type: 'string', description: 'Project slug to delete' }
+		},
+		required: ['projectSlug']
+	},
+	async (params) => {
+		let slug = guessOverEscaping(params.projectSlug).trim();
+		return await cdn.deleteProject(slug);
+	}
+);
+
+export default tools;

package/lib/ToolSet.js

@@ -132,6 +132,24 @@ class ToolSet {
 		})).sort((a, b) => a.name.localeCompare(b.name));
 	}
 
+	/**
+	 * 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) {
+		if (!(sourceToolSet instanceof ToolSet)) {
+			throw new Error('borrow() expects a ToolSet instance');
+		}
+		for (const { name } of sourceToolSet.list()) {
+			const tool = sourceToolSet.get(name);
+			this.add(name, tool.description, tool.parameters, tool.method);
+		}
+		return this;
+	}
+
 	/**
 	 * Getter for the current tool choice setting.
 	 * @returns {string} The tool choice: 'auto', 'none', or 'required'
@@ -206,4 +224,4 @@ class ToolSet {
 	}
 }
 
-export default ToolSet;
+export default ToolSet;

package/lib/cdn.js

@@ -0,0 +1,373 @@
+/**
+ * @file lib/cdn.js
+ * @module cdn
+ * @description Reusable SSH-based CDN publishing module.
+ *              Publishes any local files to a remote web server via SSH/SCP.
+ *              Designed to be used by any toolset or agent (music, images, documents, etc.).
+ *
+ * Core capabilities:
+ * - Publish single or multiple files into organized project folders
+ * - Automatically create remote directory structures
+ * - List all existing projects on the remote server
+ * - Delete entire projects when no longer needed
+ *
+ * All public URLs are built dynamically from the SSH host (assumes a web server
+ * is serving the `htdocs` directory publicly).
+ *
+ * @requires SSH_EP environment variable (format: ssh://user@host:port)
+ * @requires Remote host must have a web server serving the 'htdocs' folder
+ *
+ * @example
+ * import cdn from './cdn.js';
+ *
+ * // Publish multiple files into one project
+ * const result = await cdn.publishToProject(
+ *   ['/tmp/audio.mp3', '/tmp/cover.jpg'],
+ *   'my-song-cover-2026',
+ *   {
+ *     description: 'Cover of original song with new lyrics',
+ *     plan: 'Two-step cover using Minimax voice features'
+ *   }
+ * );
+ * console.log(result.public_urls);
+ *
+ * // List all projects
+ * const projects = await cdn.listProjects();
+ *
+ * // Delete a project
+ * await cdn.deleteProject('my-song-cover-2026');
+ */
+
+import { SH } from '@j-o-r/sh';
+import path from 'node:path';
+
+/**
+ * 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'
+ */
+function getSshConfig() {
+  if (!process.env.SSH_EP) {
+    throw new Error(
+      'Missing SSH_EP environment variable!\n' +
+      "Please set it like this: export SSH_EP='ssh://user@domain.xyz:4301'"
+    );
+  }
+
+  const ep = process.env.SSH_EP;
+  let user = '';
+  let host = '';
+  let port = 22;
+
+  try {
+    if (ep.startsWith('ssh://')) {
+      const withoutProto = ep.slice(6);
+      const [userHost, portStr] = withoutProto.split(':');
+      if (userHost.includes('@')) [user, host] = userHost.split('@');
+      else host = userHost;
+      if (portStr) port = parseInt(portStr, 10);
+    } else {
+      const [userHost, portStr] = ep.split(':');
+      if (userHost.includes('@')) [user, host] = userHost.split('@');
+      else host = userHost;
+      if (portStr) port = parseInt(portStr, 10);
+    }
+  } catch (e) {
+    throw new Error(`Failed to parse SSH_EP="${ep}": ${e.message}`);
+  }
+
+  if (!user || !host) {
+    throw new Error(`Invalid SSH_EP format: "${ep}". Expected ssh://user@host:port`);
+  }
+
+  return { user, host, port, raw: ep };
+}
+
+/**
+ * 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")
+ */
+async function ensureRemoteDir(remoteRelativeDir) {
+  const ssh = getSshConfig();
+  const remoteDir = `htdocs/${remoteRelativeDir}`;
+
+  console.log(`[cdn] Ensuring remote directory: ${remoteDir}`);
+  await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "mkdir -p ${remoteDir}"`.run();
+
+  return remoteDir;
+}
+
+/**
+ * Safely extract string output from an SH command result.
+ * Handles different return shapes from the @j-o-r/sh library.
+ *
+ * @param {any} result - Result object returned by SH.run()
+ * @returns {string} The output as a string (empty string if nothing available)
+ */
+function getOutput(result) {
+  if (!result) return '';
+  if (typeof result === 'string') return result;
+  if (result.stdout) return result.stdout.toString();
+  if (result.toString) return result.toString();
+  return '';
+}
+
+/**
+ * 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/
+ */
+async function listProjects() {
+  const ssh = getSshConfig();
+  const projectsBase = 'htdocs/projects';
+
+  console.log(`[cdn] Listing projects from ${ssh.host}...`);
+
+  try {
+    const lsResult = await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "ls -1 ${projectsBase} 2>/dev/null || echo ''"`.run();
+    const output = getOutput(lsResult);
+    const slugs = output.trim().split('\n').filter(Boolean);
+
+    const projects = [];
+
+    for (const slug of slugs) {
+      const projectDir = `${projectsBase}/${slug}`;
+
+      const countResult = await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "ls -1 ${projectDir} 2>/dev/null | wc -l"`.run();
+      const countOutput = getOutput(countResult);
+      const fileCount = parseInt(countOutput.trim(), 10) || 0;
+
+      let created;
+      try {
+        const metaResult = await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "cat ${projectDir}/meta.json 2>/dev/null || echo '{}'"`.run();
+        const metaOutput = getOutput(metaResult);
+        const meta = JSON.parse(metaOutput.trim());
+        created = meta.created;
+      } catch (_) {
+        // meta.json may not exist yet
+      }
+
+      projects.push({
+        slug,
+        url: `https://${ssh.host}/projects/${slug}/`,
+        fileCount,
+        created
+      });
+    }
+
+    console.log(`[cdn] Found ${projects.length} project(s)`);
+    return projects;
+  } catch (err) {
+    throw new Error(`Failed to list projects: ${err.message}`);
+  }
+}
+
+/**
+ * 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');
+ */
+async function deleteProject(projectSlug) {
+  const ssh = getSshConfig();
+  const slug = projectSlug.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const remoteDir = `htdocs/projects/${slug}`;
+
+  console.log(`[cdn] Deleting project: ${remoteDir}`);
+  await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "rm -rf ${remoteDir}"`.run();
+
+  console.log(`[cdn] ✅ Project deleted: ${slug}`);
+  return { deleted: true, project: slug };
+}
+
+/**
+ * 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
+ */
+async function ensureProjectStructure(projectSlug) {
+  const slug = projectSlug.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const remoteRelative = `projects/${slug}`;
+  return await ensureRemoteDir(remoteRelative);
+}
+
+/**
+ * Internal helper to upload a single file via SCP.
+ *
+ * @param {string} localPath - Local file path
+ * @param {string} remoteFilePath - Full remote path (including htdocs)
+ * @param {object} ssh - SSH config object from getSshConfig()
+ */
+async function uploadSingleFile(localPath, remoteFilePath, ssh) {
+  const scpTarget = `${ssh.user}@${ssh.host}:${remoteFilePath}`;
+  console.log(`[cdn] Uploading: ${path.basename(localPath)} → ${remoteFilePath}`);
+  await SH`scp -P ${ssh.port} ${localPath} ${scpTarget}`.run();
+}
+
+/**
+ * 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' });
+ */
+async function publishToProject(localPaths, projectSlug, options = {}) {
+  const ssh = getSshConfig();
+  const slug = projectSlug.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const remoteDir = await ensureProjectStructure(slug);
+
+  const paths = Array.isArray(localPaths) ? localPaths : [localPaths];
+  const uploadedFiles = [];
+
+  for (const localPath of paths) {
+    const filename = options.filename && paths.length === 1
+      ? options.filename
+      : path.basename(localPath);
+
+    const remoteFile = `${remoteDir}/${filename}`;
+    await uploadSingleFile(localPath, remoteFile, ssh);
+    uploadedFiles.push(filename);
+  }
+
+  const meta = {
+    project: slug,
+    created: new Date().toISOString(),
+    files: uploadedFiles,
+    source: 'cdn.js',
+    ssh_ep: ssh.raw
+  };
+
+  console.log(`[cdn] Writing meta.json`);
+  await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "cat > ${remoteDir}/meta.json << 'EOF'
+${JSON.stringify(meta, null, 2)}
+EOF"`.run();
+
+  if (options.description) {
+    await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "cat > ${remoteDir}/description.md << 'EOF'
+${options.description}
+EOF"`.run();
+  }
+
+  if (options.plan) {
+    await SH`ssh -p ${ssh.port} ${ssh.user}@${ssh.host} "cat > ${remoteDir}/plan.md << 'EOF'
+${options.plan}
+EOF"`.run();
+  }
+
+  const publicUrls = uploadedFiles.map(f => `https://${ssh.host}/projects/${slug}/${f}`);
+  const projectFolder = `https://${ssh.host}/projects/${slug}/`;
+
+  return {
+    public_urls: publicUrls,
+    project_folder: projectFolder,
+    meta
+  };
+}
+
+/**
+ * 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);
+ */
+async function publishFile(localPath, remoteRelativePath) {
+  const ssh = getSshConfig();
+  const remoteDir = path.dirname(remoteRelativePath);
+
+  if (remoteDir && remoteDir !== '.') {
+    await ensureRemoteDir(remoteDir);
+  }
+
+  const remoteTarget = `${ssh.user}@${ssh.host}:htdocs/${remoteRelativePath}`;
+
+  console.log(`[cdn] Uploading via SCP: ${localPath} → ${remoteTarget}`);
+  await SH`scp -P ${ssh.port} ${localPath} ${remoteTarget}`.run();
+  console.log(`[cdn] ✅ Upload successful`);
+
+  return {
+    public_url: `https://${ssh.host}/${remoteRelativePath}`,
+    remote_path: remoteTarget
+  };
+}
+
+export {
+  getSshConfig,
+  ensureRemoteDir,
+  ensureProjectStructure,
+  listProjects,
+  deleteProject,
+  publishFile,
+  publishToProject
+};
+
+export default {
+  getSshConfig,
+  ensureRemoteDir,
+  ensureProjectStructure,
+  listProjects,
+  deleteProject,
+  publishFile,
+  publishToProject
+};

package/lib/fafs.js

@@ -9,7 +9,9 @@ const RELATIVE_CACHE = path.resolve('.cache');
 new CacheAsync(RELATIVE_CACHE, true, 'bin');
 const APP_CACHE = path.resolve(RELATIVE_CACHE, APPNAME);
 new CacheAsync(APP_CACHE, true, 'bin');
-
+// Create the minimax temp folder
+new CacheAsync(path.resolve(RELATIVE_CACHE, 'minimax'), true, 'bin');
+new CacheAsync(path.resolve(RELATIVE_CACHE, 'stability'), true, 'bin');
 /**
  * Frequently Asked Functions (FAFS) - Utility module providing environment and system information utilities.
  *