voyageai-cli 1.28.0 → 1.30.0

package/src/lib/capability-report.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const CAP_ICONS = {
+  NETWORK: '🌐',
+  WRITE_DB: '💾',
+  LLM: '🤖',
+  LOOP: '🔄',
+  READ_DB: '📊',
+};
+
+const SEVERITY_ICONS = {
+  critical: '🔴',
+  high: '🟠',
+  medium: '🟡',
+  low: '🔵',
+};
+
+/**
+ * Generate a markdown-formatted capability report for a workflow package.
+ *
+ * @param {object} definition - Parsed workflow JSON
+ * @param {Array<{severity: string, message: string, stepId?: string}>} securityFindings
+ * @param {Array<{level: string, message: string}>} qualityIssues
+ * @param {{ total: number, passed: number, failed: number, results?: Array }} [testResults]
+ * @returns {string} Markdown-formatted report
+ */
+function generateCapabilityReport(definition, securityFindings, qualityIssues, testResults) {
+  const lines = [];
+
+  const name = definition?.name || 'Unknown Workflow';
+  lines.push(`## 📋 Workflow Validation Report: ${name}`);
+  lines.push('');
+
+  // ── Capabilities ──
+  const { extractCapabilities } = require('./security-audit');
+  const caps = definition ? [...extractCapabilities(definition)] : [];
+
+  lines.push('### Capabilities');
+  if (caps.length === 0) {
+    lines.push('No special capabilities detected.');
+  } else {
+    for (const cap of caps) {
+      lines.push(`- ${CAP_ICONS[cap] || '•'} **${cap}**`);
+    }
+  }
+  lines.push('');
+
+  // ── Security Findings ──
+  lines.push('### Security Audit');
+  if (!securityFindings || securityFindings.length === 0) {
+    lines.push('✅ No security issues found.');
+  } else {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of securityFindings) {
+      counts[f.severity] = (counts[f.severity] || 0) + 1;
+    }
+    const summary = Object.entries(counts)
+      .filter(([, v]) => v > 0)
+      .map(([k, v]) => `${SEVERITY_ICONS[k]} ${v} ${k.toUpperCase()}`)
+      .join(' | ');
+    lines.push(summary);
+    lines.push('');
+    lines.push('| Severity | Finding | Step |');
+    lines.push('|----------|---------|------|');
+    for (const f of securityFindings) {
+      lines.push(`| ${SEVERITY_ICONS[f.severity]} ${f.severity.toUpperCase()} | ${f.message} | ${f.stepId || '—'} |`);
+    }
+  }
+  lines.push('');
+
+  // ── Quality ──
+  lines.push('### Quality Audit');
+  if (!qualityIssues || qualityIssues.length === 0) {
+    lines.push('✅ No quality issues found.');
+  } else {
+    const errorCount = qualityIssues.filter(i => i.level === 'error').length;
+    const warningCount = qualityIssues.filter(i => i.level === 'warning').length;
+    const suggestionCount = qualityIssues.filter(i => i.level === 'suggestion').length;
+
+    const parts = [];
+    if (errorCount) parts.push(`❌ ${errorCount} error(s)`);
+    if (warningCount) parts.push(`⚠️ ${warningCount} warning(s)`);
+    if (suggestionCount) parts.push(`💡 ${suggestionCount} suggestion(s)`);
+    lines.push(parts.join(' | '));
+    lines.push('');
+
+    for (const issue of qualityIssues) {
+      const icon = issue.level === 'error' ? '❌' : issue.level === 'warning' ? '⚠️' : '💡';
+      lines.push(`- ${icon} **[${issue.level.toUpperCase()}]** ${issue.message}`);
+    }
+  }
+  lines.push('');
+
+  // ── Test Results ──
+  lines.push('### Test Results');
+  if (!testResults) {
+    lines.push('⏭️ No test results available.');
+  } else if (testResults.total === 0) {
+    lines.push('⏭️ No test cases found.');
+  } else {
+    const status = testResults.failed === 0 ? '✅' : '❌';
+    lines.push(`${status} **${testResults.passed}/${testResults.total}** tests passed`);
+    if (testResults.results && testResults.results.length > 0) {
+      lines.push('');
+      for (const r of testResults.results) {
+        const icon = r.passed ? '✅' : '❌';
+        lines.push(`- ${icon} ${r.name || r.file}`);
+      }
+    }
+  }
+  lines.push('');
+
+  // ── Overall Summary ──
+  const criticalCount = (securityFindings || []).filter(f => f.severity === 'critical').length;
+  const highCount = (securityFindings || []).filter(f => f.severity === 'high').length;
+  const qualityErrors = (qualityIssues || []).filter(i => i.level === 'error').length;
+  const testsFailed = testResults ? testResults.failed : 0;
+
+  lines.push('### Summary');
+  if (criticalCount === 0 && highCount === 0 && qualityErrors === 0 && testsFailed === 0) {
+    lines.push('✅ **All checks passed.** This workflow is ready for review.');
+  } else {
+    const issues = [];
+    if (criticalCount) issues.push(`${criticalCount} critical security finding(s)`);
+    if (highCount) issues.push(`${highCount} high security finding(s)`);
+    if (qualityErrors) issues.push(`${qualityErrors} quality error(s)`);
+    if (testsFailed) issues.push(`${testsFailed} test failure(s)`);
+    lines.push(`⚠️ **Issues found:** ${issues.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { generateCapabilityReport };

package/src/lib/chat.js

@@ -202,9 +202,15 @@ async function* chatTurn({ query, db, collection, llm, history, opts = {} }) {
   // 3. Generate response (streaming)
   let fullResponse = '';
   const stream = opts.stream !== false;
+  let llmUsage = { inputTokens: 0, outputTokens: 0 };
 
   try {
     for await (const chunk of llm.chat(messages, { stream })) {
+      // Check for __usage sentinel (yielded as final item from LLM providers)
+      if (typeof chunk === 'object' && chunk !== null && chunk.__usage) {
+        llmUsage = chunk.__usage;
+        continue;
+      }
       fullResponse += chunk;
       yield { type: 'chunk', data: chunk };
     }
@@ -240,7 +246,13 @@ async function* chatTurn({ query, db, collection, llm, history, opts = {} }) {
       metadata: {
         retrievalTimeMs,
         generationTimeMs,
-        tokens,
+        tokens: {
+          ...tokens,
+          llmInput: llmUsage.inputTokens,
+          llmOutput: llmUsage.outputTokens,
+        },
+        llmModel: llm.model,
+        llmProvider: llm.name,
         contextDocsUsed: docs.length,
       },
     },
@@ -284,11 +296,18 @@ async function* agentChatTurn({ query, llm, history, opts = {} }) {
   // Track messages for the tool-calling loop (mutable copy)
   const messages = [...initialMessages];
   const toolCallLog = [];
+  const totalLlmUsage = { inputTokens: 0, outputTokens: 0 };
 
   // 3. Agent loop
   for (let iteration = 0; iteration < maxIterations; iteration++) {
     const response = await llm.chatWithTools(messages, tools);
 
+    // Accumulate LLM usage from each chatWithTools call
+    if (response.usage) {
+      totalLlmUsage.inputTokens += response.usage.inputTokens || 0;
+      totalLlmUsage.outputTokens += response.usage.outputTokens || 0;
+    }
+
     // Text response: done
     if (response.type === 'text') {
       const fullResponse = response.content;
@@ -321,6 +340,12 @@ async function* agentChatTurn({ query, llm, history, opts = {} }) {
             iterationCount: iteration + 1,
             toolCallCount: toolCallLog.length,
             totalTimeMs,
+            tokens: {
+              llmInput: totalLlmUsage.inputTokens,
+              llmOutput: totalLlmUsage.outputTokens,
+            },
+            llmModel: llm.model,
+            llmProvider: llm.name,
           },
         },
       };
@@ -406,6 +431,12 @@ async function* agentChatTurn({ query, llm, history, opts = {} }) {
         toolCallCount: toolCallLog.length,
         totalTimeMs: Date.now() - start,
         maxIterationsReached: true,
+        tokens: {
+          llmInput: totalLlmUsage.inputTokens,
+          llmOutput: totalLlmUsage.outputTokens,
+        },
+        llmModel: llm.model,
+        llmProvider: llm.name,
       },
     },
   };

package/src/lib/config.js

@@ -18,6 +18,8 @@ const KEY_MAP = {
   'llm-api-key': 'llmApiKey',
   'llm-model': 'llmModel',
   'llm-base-url': 'llmBaseUrl',
+  'show-cost': 'show-cost',
+  'telemetry': 'telemetry',
 };
 
 // Keys whose values should be masked in output

package/src/lib/cost-display.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const { MODEL_CATALOG } = require('./catalog');
+const { getConfigValue } = require('./config');
+const ui = require('./ui');
+
+const COMPETITOR_PRICE = 0.13; // OpenAI text-embedding-3-large per 1M tokens
+const LARGE_PRICE = 0.12;     // voyage-4-large per 1M tokens
+
+/**
+ * Show a one-line cost summary after a CLI operation.
+ * Only displays when `show-cost` config is enabled.
+ * Respects --json and --quiet flags.
+ *
+ * @param {string} model - Model name used
+ * @param {number} tokens - Total tokens consumed
+ * @param {object} [opts] - Command options
+ * @param {boolean} [opts.json] - JSON output mode (suppress cost)
+ * @param {boolean} [opts.quiet] - Quiet mode (suppress cost)
+ */
+function showCostSummary(model, tokens, opts = {}) {
+  if (opts.json || opts.quiet) return;
+  if (!isEnabled()) return;
+  if (!tokens || tokens <= 0) return;
+
+  const entry = MODEL_CATALOG.find(m => m.name === model);
+  const price = entry?.pricePerMToken ?? LARGE_PRICE;
+  const cost = (tokens / 1_000_000) * price;
+  const largeCost = (tokens / 1_000_000) * LARGE_PRICE;
+
+  const costStr = formatCost(cost);
+  const tokStr = tokens.toLocaleString();
+
+  console.log();
+  console.log(ui.dim(`  💰 ${costStr} (${tokStr} tokens, ${model})`));
+
+  if (price < LARGE_PRICE) {
+    const savingsPercent = Math.round((1 - price / LARGE_PRICE) * 100);
+    const largeStr = formatCost(largeCost);
+    console.log(ui.dim(`     Symmetric (voyage-4-large): ${largeStr} — ${savingsPercent}% savings`));
+  }
+}
+
+/**
+ * Show a combined cost summary for operations with multiple API calls
+ * (e.g., query with embed + rerank).
+ *
+ * @param {Array<{model: string, tokens: number, label?: string}>} operations
+ * @param {object} [opts]
+ */
+function showCombinedCostSummary(operations, opts = {}) {
+  if (opts.json || opts.quiet) return;
+  if (!isEnabled()) return;
+
+  let totalCost = 0;
+  let totalLargeCost = 0;
+  let totalTokens = 0;
+
+  for (const op of operations) {
+    if (!op.tokens || op.tokens <= 0) continue;
+    const entry = MODEL_CATALOG.find(m => m.name === op.model);
+    const price = entry?.pricePerMToken ?? LARGE_PRICE;
+    totalCost += (op.tokens / 1_000_000) * price;
+    totalLargeCost += (op.tokens / 1_000_000) * LARGE_PRICE;
+    totalTokens += op.tokens;
+  }
+
+  if (totalTokens <= 0) return;
+
+  console.log();
+  console.log(ui.dim(`  💰 ${formatCost(totalCost)} total (${totalTokens.toLocaleString()} tokens)`));
+  for (const op of operations) {
+    if (!op.tokens || op.tokens <= 0) continue;
+    const entry = MODEL_CATALOG.find(m => m.name === op.model);
+    const price = entry?.pricePerMToken ?? LARGE_PRICE;
+    const cost = (op.tokens / 1_000_000) * price;
+    const label = op.label || op.model;
+    console.log(ui.dim(`     ${label}: ${formatCost(cost)} (${op.tokens.toLocaleString()} tokens)`));
+  }
+
+  if (totalCost < totalLargeCost) {
+    const savingsPercent = Math.round((1 - totalCost / totalLargeCost) * 100);
+    console.log(ui.dim(`     Symmetric (all voyage-4-large): ${formatCost(totalLargeCost)} — ${savingsPercent}% savings`));
+  }
+}
+
+/**
+ * Check if cost display is enabled via config.
+ * @returns {boolean}
+ */
+function isEnabled() {
+  const val = getConfigValue('show-cost');
+  return val === true || val === 'true';
+}
+
+/**
+ * Format a cost value for display.
+ * @param {number} cost
+ * @returns {string}
+ */
+function formatCost(cost) {
+  if (cost < 0.000001) return '$0.000000';
+  if (cost < 0.01) return `$${cost.toFixed(6)}`;
+  return `$${cost.toFixed(4)}`;
+}
+
+module.exports = { showCostSummary, showCombinedCostSummary, isEnabled, formatCost };

package/src/lib/explanations.js

@@ -589,9 +589,15 @@ const concepts = {
       ``,
       `${pc.bold('Validate it yourself:')} Use ${pc.cyan('vai benchmark space')} to embed identical text`,
       `with all Voyage 4 models and see the cross-model cosine similarities.`,
+      ``,
+      `${pc.bold('Interactive proof:')} Try the ${pc.cyan('Shared Space Explorer')} at`,
+      `${pc.cyan('vaicli.com/shared-space')} — embed text with all three models simultaneously`,
+      `and see 0.95+ cross-model similarity in a live 3×3 matrix, scatter plot, and`,
+      `cost comparison. Share your results directly to LinkedIn.`,
     ].join('\n'),
     links: [
       'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://vaicli.com/shared-space',
     ],
     tryIt: [
       'vai benchmark space',
@@ -1478,6 +1484,87 @@ const concepts = {
       'vai workflow run multi-collection-search --input query="test" --dry-run',
     ],
   },
+
+  'workflow-publishing': {
+    title: 'Publishing vai Workflows to npm',
+    summary: 'Share workflows as npm packages using the vai-workflow-* convention',
+    content: [
+      `${pc.bold('WHAT IS A WORKFLOW PACKAGE?')}`,
+      ``,
+      `A vai workflow package is an npm package containing a reusable workflow`,
+      `definition. It follows the naming convention ${pc.cyan('vai-workflow-<name>')} and contains:`,
+      ``,
+      `  • ${pc.cyan('workflow.json')}  — The workflow definition (same format as any vai workflow)`,
+      `  • ${pc.cyan('package.json')}   — npm metadata + vai-specific fields`,
+      `  • ${pc.cyan('README.md')}      — Usage instructions`,
+      ``,
+      `No JavaScript, no build step, no dependencies.`,
+      ``,
+      `${pc.bold('HOW TO PUBLISH')}`,
+      ``,
+      `Option 1: Package an existing workflow`,
+      ``,
+      `  ${pc.cyan('vai workflow create --from my-workflow.json --name my-workflow')}`,
+      ``,
+      `  This creates a ${pc.cyan('vai-workflow-my-workflow/')} directory with everything needed.`,
+      `  Review it, then:`,
+      ``,
+      `  ${pc.cyan('cd vai-workflow-my-workflow')}`,
+      `  ${pc.cyan('npm publish')}`,
+      ``,
+      `Option 2: Start from scratch`,
+      ``,
+      `  ${pc.cyan('vai workflow create --name my-workflow')}`,
+      ``,
+      `  This creates an interactive template you can fill in.`,
+      ``,
+      `${pc.bold('PACKAGE.JSON REQUIREMENTS')}`,
+      ``,
+      `Your package.json needs a ${pc.cyan('"vai"')} field with:`,
+      ``,
+      `  {`,
+      `    "vai": {`,
+      `      "workflowVersion": "1.0",`,
+      `      "tools": ["query", "rerank"],`,
+      `      "category": "retrieval"`,
+      `    }`,
+      `  }`,
+      ``,
+      `${pc.cyan('vai workflow create')} fills this in automatically.`,
+      ``,
+      `${pc.bold('NAMING')}`,
+      ``,
+      `Package names must start with ${pc.cyan('vai-workflow-')} followed by a lowercase, hyphenated name:`,
+      ``,
+      `  ${pc.green('✓')} vai-workflow-legal-research`,
+      `  ${pc.green('✓')} vai-workflow-code-review`,
+      `  ${pc.red('✗')} vai-legal-workflow  (wrong prefix)`,
+      ``,
+      `${pc.bold('CATEGORIES')}`,
+      ``,
+      `  ${pc.cyan('retrieval')}        — Search and retrieval pipelines`,
+      `  ${pc.cyan('analysis')}         — Comparison, consistency checking`,
+      `  ${pc.cyan('ingestion')}        — Document processing and storage`,
+      `  ${pc.cyan('domain-specific')}  — Industry-focused (legal, clinical, etc.)`,
+      `  ${pc.cyan('utility')}          — Cost estimation, benchmarking`,
+      `  ${pc.cyan('integration')}      — Multi-system workflows`,
+      ``,
+      `${pc.bold('TESTING BEFORE PUBLISHING')}`,
+      ``,
+      `  ${pc.cyan('vai workflow validate ./vai-workflow-my-workflow/workflow.json')}`,
+      `  ${pc.cyan('npm install ./vai-workflow-my-workflow')}`,
+      `  ${pc.cyan('vai workflow run vai-workflow-my-workflow --dry-run')}`,
+    ].join('\n'),
+    links: [
+      'https://github.com/mrlynn/voyageai-cli',
+    ],
+    tryIt: [
+      'vai workflow create --from my-pipeline.json --name my-pipeline',
+      'vai workflow create',
+      'vai workflow search legal',
+      'vai workflow install vai-workflow-legal-research',
+    ],
+  },
 };
 
 /**
@@ -1651,6 +1738,13 @@ const aliases = {
   'vai-workflow': 'workflows',
   pipeline: 'workflows',
   dag: 'workflows',
+  // Workflow publishing aliases
+  'workflow-publishing': 'workflow-publishing',
+  'publish-workflow': 'workflow-publishing',
+  'workflow-registry': 'workflow-publishing',
+  'community-workflows': 'workflow-publishing',
+  'share-workflow': 'workflow-publishing',
+  'npm-workflow': 'workflow-publishing',
 };
 
 /**