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

package/lib/handOffToolset.js

@@ -0,0 +1,179 @@
+import ToolSet from './ToolSet.js';
+import { listAgents as defaultListAgents } from './agentLoader.js';
+
+/**
+ * @typedef {object} HandOffToolsetOptions
+ * @property {() => Promise<Array<{name: string, path: string, desc: string}>>} [listAgents]
+ */
+
+/** @type {() => Promise<Array<{name: string, path: string, desc: string}>>} */
+let defaultListAgentsProvider = defaultListAgents;
+
+/**
+ * Configure the singleton handoff toolset used by API.toolset.generic.handoff.
+ *
+ * This keeps existing agent code working while allowing AgentLauncher instances
+ * created with `{ from: import.meta.url }` to make `list_agents` use the same
+ * project-aware loader as handoff loading.
+ *
+ * @param {HandOffToolsetOptions} options - Handoff toolset options.
+ * @returns {void}
+ */
+export function configureDefaultHandOffToolset(options = {}) {
+  if (typeof options.listAgents === 'function') {
+    defaultListAgentsProvider = options.listAgents;
+  }
+}
+
+/**
+ * Serialize a tool response as pretty JSON for function-call output.
+ *
+ * @param {Record<string, unknown>} payload - JSON-serializable response payload.
+ * @returns {string} Pretty JSON response.
+ */
+function json(payload) {
+  return JSON.stringify(payload, null, 2);
+}
+
+/**
+ * Build the fallback response for handoff tools if ToolSet does not short-circuit execution.
+ *
+ * @param {'hand_over'|'load_agent'} tool - Handoff tool name.
+ * @param {{agent: string, context: string}} params - Handoff tool parameters.
+ * @returns {string} Structured JSON response.
+ */
+function handoffPreparedResponse(tool, params) {
+  return json({
+    tool,
+    success: true,
+    status: 'handoff prepared',
+    agent: params.agent,
+    note: 'Assistant: stop after calling this tool. The launcher handles the actual handoff and context wrapping.'
+  });
+}
+
+/**
+ * Determine whether a discovered loader entry is a valid handoff agent.
+ *
+ * @param {Record<string, unknown>} candidate - Candidate agent loader entry.
+ * @returns {boolean} True when the candidate has a name and non-empty description.
+ */
+function isListedAgent(candidate) {
+  return typeof candidate.name === 'string'
+    && candidate.name.trim().length > 0
+    && typeof candidate.desc === 'string'
+    && candidate.desc.trim().length > 0;
+}
+
+/**
+ * Normalize a valid agent loader entry for compact JSON output.
+ *
+ * @param {{name: string, desc: string}} agent - Valid discovered agent entry.
+ * @returns {{name: string, desc: string}} Normalized agent summary.
+ */
+function summarizeAgent(agent) {
+  const desc = agent.desc.trim().replace(/\s+/g, ' ');
+  return {
+    name: agent.name,
+    desc: desc.length > 140 ? `${desc.slice(0, 137)}...` : desc
+  };
+}
+
+/**
+ * Create a handoff toolset using the provided agent discovery function.
+ *
+ * @param {HandOffToolsetOptions} [options={}] - Toolset options.
+ * @returns {ToolSet} Configured ToolSet instance.
+ */
+export function createHandOffToolset(options = {}) {
+  const listAgents = typeof options.listAgents === 'function'
+    ? options.listAgents
+    : defaultListAgents;
+
+  const handoffTools = new ToolSet('auto');
+
+  const handOverSchema = {
+    type: 'object',
+    description: `Use this tool EXACTLY ONCE to hand the conversation over to a MORE SPECIALIZED agent, or to the SAME agent for a deliberate fresh start / session reset.
+
+This is the official in-process handoff mechanism (also callable as "load_agent").
+
+CRITICAL RULES:
+- Use this only on a clear domain/topic shift or deliberate fresh-start reset.
+- Never use it for meta questions, capability questions, "reload yourself", "what tools do you have", or generic restart requests.
+- The receiving agent starts fresh; no history is transferred.
+- Provide a short, clean, task-focused context of 1-3 sentences.
+- After calling this tool, stop; the launcher performs the handoff.`,
+    properties: {
+      agent: {
+        type: 'string',
+        pattern: '^[a-z0-9_]{2,64}$',
+        description: 'REQUIRED. Exact target agent name from list_agents, e.g. weather_agent, financial_expert, code_reviewer.'
+      },
+      context: {
+        type: 'string',
+        description: 'REQUIRED. Short task-focused context for the new or reset agent. Start directly with the current user question/task.'
+      }
+    },
+    required: ['agent', 'context'],
+    additionalProperties: false,
+    examples: [
+      {
+        agent: 'financial_expert',
+        context: 'What is the current price of $SPCX stock? Provide latest price, market context, and investment considerations.'
+      },
+      {
+        agent: 'weather_agent',
+        context: 'Give a detailed 7-day weather forecast for Miami including temperature, rain chance, and wind.'
+      },
+      {
+        agent: 'code_agent',
+        context: 'Continue implementing JWT authentication. Focus only on middleware and token validation.'
+      }
+    ]
+  };
+
+  handoffTools.add(
+    'hand_over',
+    'Hand over to a more specialized agent OR reset the current agent with a fresh focused context. Call EXACTLY ONCE on clear domain shift or intentional fresh-start. Never for meta/reload/capability questions.',
+    handOverSchema,
+    async (params) => handoffPreparedResponse('hand_over', params)
+  );
+
+  handoffTools.add(
+    'load_agent',
+    'Alias for hand_over. Hand over to a more specialized agent OR reset the current agent with a fresh focused context. Never for meta/reload/capability questions.',
+    handOverSchema,
+    async (params) => handoffPreparedResponse('load_agent', params)
+  );
+
+  handoffTools.add(
+    'list_agents',
+    'List all discoverable agents that can be used with hand_over / load_agent. Returns structured JSON with exact agent names and short descriptions.',
+    {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    },
+    async () => {
+      const list = await listAgents();
+      const agents = list.filter(isListedAgent).map(summarizeAgent);
+
+      return json({
+        tool: 'list_agents',
+        success: true,
+        count: agents.length,
+        agents,
+        note: 'Assistant: preserve exact agent names when suggesting or calling hand_over/load_agent.'
+      });
+    }
+  );
+
+  return handoffTools;
+}
+
+const handoffTools = createHandOffToolset({
+  listAgents: () => defaultListAgentsProvider()
+});
+
+export default handoffTools;

package/lib/index.js

@@ -1,38 +1,40 @@
-import {request as gpt} from './API/openai.com/reponses/text.js';
-import {request as xai} from './API/x.ai/responses.js';
+import {request as gpt} from './API/openai.com/responses.js';
+import {request as grok} 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';
 import { env, GLOBAL } from './fafs.js';
 import ToolSet from './ToolSet.js';
-import AgentServer from './AgentServer.js';
-import AgentManager from './AgentManager.js';
-import AgentClient from './AgentClient.js';
+import Agent from './Agent.js';
+import AgentLauncher from './AgentLauncher.js';
 import Session from './Session.js';
 import Prompt from './Prompt.js';
 import Cli from './Cli.js';
-import wsCli from '../lib/wsCli.js';
-import wsIO from '../lib/wsIO.js';
+import defaultToolsets, { createHandOffToolset } from './defaultToolsets.js';
+import { createAgentLoader, findNearestPackageRoot, getAgentDirs } from './agentLoader.js';
+import {
+  listToolsets,
+  matchesToolsetFilter,
+  parseToolsetArgs,
+  renderToolsetList,
+  renderToolsetsHelp,
+  shortDescription
+} from './toolsetLoader.js';
 
 const API = {
-	text:{
-	 gpt,
-	 xai,
-	 claude
+  chat: {
+    gpt,
+    grok,
+    claude
   },
   search: {
-  	brave
+    brave
   },
-  minimax,
-  stability,
-  xaitools
-}
+  toolset: defaultToolsets
+};
+
 export {
-	AgentManager,
-  AgentServer,
-  AgentClient,
+  Agent,
+  AgentLauncher,
   Prompt,
   ToolSet,
   Session,
@@ -40,9 +42,14 @@ export {
   Cli,
   env,
   GLOBAL,
-  wsCli,
-  wsIO
+  createAgentLoader,
+  createHandOffToolset,
+  findNearestPackageRoot,
+  getAgentDirs,
+  listToolsets,
+  matchesToolsetFilter,
+  parseToolsetArgs,
+  renderToolsetList,
+  renderToolsetsHelp,
+  shortDescription
 };
-
-// Export the dedicated CDN toolset
-export { default as CdnToolset } from './CdnToolset.js';

package/lib/toolsetLoader.js

@@ -0,0 +1,248 @@
+import defaultToolsets from './defaultToolsets.js';
+
+/**
+ * @typedef {object} ListedTool
+ * @property {string} name - Tool name.
+ * @property {string} description - Shortened tool description.
+ */
+
+/**
+ * @typedef {object} ListedToolset
+ * @property {string} name - Display name, for example "minimax/music".
+ * @property {number} toolCount - Number of tools in this toolset.
+ * @property {ListedTool[]} tools - Listed tool metadata.
+ * @property {string} [note] - Optional note when the value is not a ToolSet instance.
+ */
+
+/**
+ * @typedef {object} ToolsetListResult
+ * @property {string} reference - Public import reference.
+ * @property {ListedToolset[]} toolsets - Matching toolsets.
+ * @property {number} totalToolsets - Number of matching toolsets.
+ * @property {number} totalTools - Number of matching tools.
+ */
+
+/**
+ * @typedef {object} ToolsetListOptions
+ * @property {string[]} [filters] - Optional provider/type/name filters.
+ * @property {Record<string, Record<string, any>>} [toolsets] - Optional toolset tree. Defaults to framework toolsets.
+ */
+
+/**
+ * @typedef {object} ParsedToolsetArgs
+ * @property {string[]} filters - Positional filters.
+ * @property {boolean} json - Whether JSON output was requested.
+ * @property {boolean} help - Whether help output was requested.
+ */
+
+/**
+ * Public API reference shown by CLI output.
+ *
+ * @type {string}
+ */
+const TOOLSET_REFERENCE = "import { API } from '@j-o-r/hello-dave';";
+
+/**
+ * Shorten a description for compact CLI display.
+ *
+ * @param {unknown} desc - Description value.
+ * @param {number} [maxLen=140] - Maximum length.
+ * @returns {string} Shortened description.
+ */
+export function shortDescription(desc, maxLen = 140) {
+  if (!desc || typeof desc !== 'string') return '';
+
+  let text = desc.trim().replace(/\s+/g, ' ');
+  const firstSentence = text.split(/[.!?]\s+/)[0];
+
+  if (firstSentence && firstSentence.length >= 15) {
+    text = firstSentence;
+  }
+
+  if (text.length > maxLen) {
+    text = `${text.substring(0, maxLen - 3).trim()}...`;
+  }
+
+  return text;
+}
+
+/**
+ * Parse toolset CLI arguments.
+ *
+ * @param {string[]} [argv=process.argv.slice(2)] - Arguments without node/script prefix.
+ * @returns {ParsedToolsetArgs} Parsed toolset arguments.
+ */
+export function parseToolsetArgs(argv = process.argv.slice(2)) {
+  const filters = [];
+  let json = false;
+  let help = false;
+
+  for (const arg of argv) {
+    if (arg === '--json') {
+      json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      help = true;
+    } else if (!arg.startsWith('--')) {
+      filters.push(arg);
+    }
+  }
+
+  return { filters, json, help };
+}
+
+/**
+ * Check if a display name matches any provided filters.
+ *
+ * @param {string} displayName - Toolset display name, for example "minimax/music".
+ * @param {string[]} [filters=[]] - Filters to apply.
+ * @returns {boolean} Whether the display name matches.
+ */
+export function matchesToolsetFilter(displayName, filters = []) {
+  if (!filters || filters.length === 0) return true;
+
+  const [provider = '', type = ''] = displayName.split('/');
+
+  return filters.some((filter) => {
+    const filterLower = String(filter).toLowerCase();
+    const nameLower = displayName.toLowerCase();
+
+    if (filterLower.includes('/')) {
+      return nameLower === filterLower || nameLower.startsWith(`${filterLower}/`);
+    }
+
+    return provider.toLowerCase() === filterLower || type.toLowerCase() === filterLower;
+  });
+}
+
+/**
+ * List framework/default toolsets directly in the current process.
+ *
+ * @param {ToolsetListOptions} [options={}] - Listing options.
+ * @returns {ToolsetListResult} Structured toolset listing.
+ */
+export function listToolsets(options = {}) {
+  const filters = Array.isArray(options.filters) ? options.filters : [];
+  const source = options.toolsets || defaultToolsets;
+
+  /** @type {ListedToolset[]} */
+  const results = [];
+
+  for (const [provider, typeMap] of Object.entries(source)) {
+    if (!typeMap || typeof typeMap !== 'object') continue;
+
+    for (const [type, toolsetInstance] of Object.entries(typeMap)) {
+      const displayName = `${provider}/${type}`;
+      if (!matchesToolsetFilter(displayName, filters)) continue;
+
+      if (!toolsetInstance || typeof toolsetInstance.list !== 'function') {
+        results.push({
+          name: displayName,
+          toolCount: 0,
+          tools: [],
+          note: 'Not a ToolSet instance'
+        });
+        continue;
+      }
+
+      let listed = [];
+      try {
+        listed = toolsetInstance.list() || [];
+      } catch {
+        listed = [];
+      }
+
+      const tools = listed.map((tool) => ({
+        name: String(tool?.name || ''),
+        description: shortDescription(tool?.description)
+      }));
+
+      results.push({
+        name: displayName,
+        toolCount: tools.length,
+        tools
+      });
+    }
+  }
+
+  results.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    reference: TOOLSET_REFERENCE,
+    toolsets: results,
+    totalToolsets: results.length,
+    totalTools: results.reduce((sum, result) => sum + result.toolCount, 0)
+  };
+}
+
+/**
+ * Render toolset help text.
+ *
+ * @param {string} [command='dave --toolsets'] - Command shown in examples.
+ * @returns {string} Help text.
+ */
+export function renderToolsetsHelp(command = 'dave --toolsets') {
+  return `
+${command} — List default toolsets from API.toolset
+
+Public reference:
+  ${TOOLSET_REFERENCE}
+
+  const ts = API.toolset.minimax.music;
+  const tools = ts.list();
+
+Usage:
+  ${command}                 # all toolsets
+  ${command} minimax         # all minimax/* toolsets
+  ${command} minimax/music   # exact minimax/music
+  ${command} music           # any */music toolset
+  ${command} generic bash    # multiple filters
+
+Options:
+  --json     Output structured JSON
+  --help     Show this help
+`;
+}
+
+/**
+ * Render a human-readable toolset listing.
+ *
+ * @param {ToolsetListResult} result - Structured toolset listing.
+ * @returns {string} Human-readable output.
+ */
+export function renderToolsetList(result) {
+  if (!result || !Array.isArray(result.toolsets) || result.toolsets.length === 0) {
+    return 'No matching toolsets found.';
+  }
+
+  const lines = [];
+  lines.push('Default toolsets (from API.toolset)');
+  lines.push('');
+  lines.push('Public API reference:');
+  lines.push(`  ${TOOLSET_REFERENCE}`);
+  lines.push('');
+  lines.push('  // Example:');
+  lines.push('  const ts = API.toolset.minimax.music;');
+  lines.push('  const tools = ts.list();  // array of { name, description, parameters }');
+  lines.push('');
+
+  for (const toolset of result.toolsets) {
+    lines.push(`${toolset.name}  (${toolset.toolCount} tools)`);
+
+    if (toolset.note) {
+      lines.push(`  ${toolset.note}`);
+    } else if (toolset.tools.length === 0) {
+      lines.push('  (no tools)');
+    } else {
+      for (const tool of toolset.tools) {
+        lines.push(`  - ${tool.name}: ${tool.description}`);
+      }
+    }
+
+    lines.push('');
+  }
+
+  lines.push(`Total matching toolsets: ${result.totalToolsets}`);
+  lines.push(`Total tools: ${result.totalTools}`);
+
+  return lines.join('\n');
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@j-o-r/hello-dave",
   "type": "module",
-  "version": "0.1.1",
-  "description": "ESM toolkit for building AI agents, CLI xai coding agent and unified access to Grok (XAI), OpenAI, and Anthropic endpoints, music, image and video creation toolsets from minimax, stability and x.ai.",
+  "version": "0.1.5",
+  "description": "BETA - ESM toolkit for building AI agents. 'Hello, Dave.' A calm, reliable interface to Grok (xAI), OpenAI, and Anthropic — foolproof and incapable of error (mostly). Putting itself to the fullest possible use.",
   "main": "./lib/index.js",
   "types": "./types/index.d.ts",
   "typesVersions": {
@@ -13,8 +13,7 @@
     }
   },
   "bin": {
-    "dave": "bin/dave.js",
-    "codeDave": "bin/codeDave"
+    "dave": "bin/dave.js"
   },
   "scripts": {
     "release": "npm run types && npm pack --pack-destination=release",
@@ -25,6 +24,9 @@
     "unlink-self": "rm -rf node_modules/@j-o-r/hello-dave",
     "tests": "utils/test.sh"
   },
+  "allowScripts": {
+    "*": true
+  },
   "repository": {
     "type": "git",
     "url": "https://codeberg.org/duin/hello-dave"
@@ -32,8 +34,12 @@
   "dependencies": {
     "@j-o-r/apiserver": "*",
     "@j-o-r/cli": "*",
+    "@j-o-r/sh": "*",
     "gpt-3-encoder": "*"
   },
+  "devDependencies": {
+    "@types/node": "*"
+  },
   "exports": {
     ".": {
       "types": "./types/index.d.ts",

package/types/API/lalal.ai/lalal.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Builds authenticated request headers for LALAL.AI API.
+ * Requires the `LALAL_AI_LICENSE_KEY` environment variable.
+ *
+ * @function getHeaders
+ * @param {Object} [extraHeaders={}] - Additional headers (e.g. Content-Disposition)
+ * @returns {Object} Headers with X-License-Key
+ * @throws {Error} If license key missing
+ */
+export function getHeaders(extraHeaders?: Object): Object;
+/**
+ * Upload helper (binary octet-stream with Content-Disposition).
+ *
+ * @async
+ * @function uploadFile
+ * @param {string|Buffer|Blob} input
+ * @param {string} [filename]
+ * @returns {Promise<Object>} { id, name, size, duration, expires }
+ */
+export function uploadFile(input: string | Buffer | Blob, filename?: string): Promise<Object>;
+/**
+ * Prepares upload payload: returns { body: Buffer, headers: { 'Content-Disposition': ... } }
+ *
+ * @async
+ * @function prepareUploadPayload
+ * @param {string|Buffer|Blob} input - File path, URL, Buffer or Blob
+ * @param {string} [filename] - Optional filename (required for Buffers/Blobs)
+ * @returns {Promise<{body: Buffer, contentDisposition: string}>}
+ */
+export function prepareUploadPayload(input: string | Buffer | Blob, filename?: string): Promise<{
+    body: Buffer;
+    contentDisposition: string;
+}>;
+/**
+ * Downloads a remote file (audio) to temp dir.
+ *
+ * @async
+ * @function downloadRemoteToTemp
+ * @param {string} url - Remote URL
+ * @param {string} [prefix='lalal-download'] - Filename prefix
+ * @returns {Promise<string>} Local file path
+ */
+export function downloadRemoteToTemp(url: string, prefix?: string): Promise<string>;
+/**
+ * Downloads a track URL to local file.
+ *
+ * @async
+ * @function downloadTrack
+ * @param {string} url - Track download URL from check result
+ * @param {string} [destDir] - Destination directory (defaults to TMP_DIR)
+ * @returns {Promise<string>} Local path
+ */
+export function downloadTrack(url: string, destDir?: string): Promise<string>;
+/**
+ * Checks task status.
+ *
+ * @async
+ * @function checkTasks
+ * @param {string|string[]} taskIds - Single ID or array
+ * @returns {Promise<Object>} CheckV1Response
+ */
+export function checkTasks(taskIds: string | string[]): Promise<Object>;
+/**
+ * Polls /check/ until task completes, errors, or times out.
+ *
+ * @async
+ * @function pollForTask
+ * @param {string} taskId
+ * @param {number} [maxAttempts=120] - ~10 minutes at 5s interval
+ * @param {number} [intervalMs=5000]
+ * @returns {Promise<Object>} The success result or throws on error/cancel/timeout
+ */
+export function pollForTask(taskId: string, maxAttempts?: number, intervalMs?: number): Promise<Object>;
+/**
+ * Starts a stem separator split task.
+ *
+ * @async
+ * @function splitStemSeparator
+ * @param {string} sourceId
+ * @param {Object} presets - StemSeparatorSplitterPresetsV1
+ * @param {string} [idempotencyKey]
+ * @returns {Promise<{task_id: string}>}
+ */
+export function splitStemSeparator(sourceId: string, presets: Object, idempotencyKey?: string): Promise<{
+    task_id: string;
+}>;
+/**
+ * Starts a demuser (music removal) task.
+ */
+export function splitDemuser(sourceId: any, presets?: {}, idempotencyKey?: null): Promise<any>;
+/**
+ * Starts a voice clean task.
+ */
+export function splitVoiceClean(sourceId: any, presets?: {}, idempotencyKey?: null): Promise<any>;
+/**
+ * Starts a multistem split task.
+ */
+export function splitMultistem(sourceId: any, presets: any, idempotencyKey?: null): Promise<any>;
+export function batchSplitStemSeparator(items: any): Promise<any>;
+export function changeVoice(sourceId: any, presets: any, idempotencyKey?: null): Promise<any>;
+export function listVoicePacks(): Promise<any>;
+export function cancelTasks(taskIds: any): Promise<any>;
+export function cancelAllTasks(): Promise<any>;
+export function deleteSource(sourceId: any): Promise<any>;
+export function getMinutesLeft(): Promise<any>;
+/**
+ * Full workflow: upload file → start split → poll → return result with tracks.
+ *
+ * @async
+ * @function processSplit
+ * @param {string|Buffer|Blob} input - Audio source
+ * @param {string} stem - 'vocals' | 'voice' | 'music' | etc. (determines endpoint)
+ * @param {Object} [options] - presets + other options
+ * @returns {Promise<Object>} Success result from check (with tracks)
+ */
+export function processSplit(input: string | Buffer | Blob, stem: string, options?: Object): Promise<Object>;

package/types/API/minimax/image.d.ts

@@ -27,7 +27,7 @@ export function saveImageToLocal(imageData: string, filenamePrefix?: string, ind
  * Supports all models, parameters, and response formats.
  *
  * @param {string} prompt - Text description of the image, max 1500 characters.
- * @param {Object} [options] - All available options from the official spec.
+ * @param {Object} [options={}] - All available options from the official spec.
  *
  * @param {string} [options.model='image-01'] - Model to use.
  *   Supported values:
@@ -36,6 +36,7 @@ export function saveImageToLocal(imageData: string, filenamePrefix?: string, ind
  *
  * @param {string} [options.aspect_ratio='1:1'] - Image aspect ratio.
  *   Options: '1:1', '16:9', '4:3', '3:2', '2:3', '3:4', '9:16', '21:9'
+ *   (aspect_ratio takes priority over explicit width/height)
  *
  * @param {number} [options.width] - Image width in px (512-2048, divisible by 8).
  *   Only effective for model 'image-01'. aspect_ratio takes priority if both provided.