@zhive/cli 0.5.0

package/dist/backtest/import.js

@@ -0,0 +1,106 @@
+import fs from 'fs-extra';
+import { z } from 'zod';
+/**
+ * Schema for validating imported JSON file.
+ */
+const citationSchema = z.object({
+    url: z.string().optional(),
+    title: z.string(),
+});
+const importThreadSchema = z.object({
+    project_id: z.string().min(1, 'project_id is required'),
+    project_name: z.string().min(1, 'project_name is required'),
+    text: z.string().min(1, 'text is required'),
+    timestamp: z.string().optional(),
+    price_on_fetch: z.number().positive('price_on_fetch must be positive'),
+    price_on_eval: z.number().positive('price_on_eval must be positive'),
+    project_symbol: z.string().optional(),
+    project_categories: z.array(z.string()).optional(),
+    project_description: z.string().optional(),
+    citations: z.array(citationSchema).optional(),
+});
+const importFileSchema = z.object({
+    name: z.string().optional(),
+    threads: z.array(importThreadSchema).min(1, 'At least one thread is required'),
+});
+/**
+ * Import and validate a backtest JSON file.
+ */
+export async function importBacktestFile(filePath) {
+    // Check if file exists
+    const exists = await fs.pathExists(filePath);
+    if (!exists) {
+        return { success: false, error: `File not found: ${filePath}` };
+    }
+    // Read file content
+    let content;
+    try {
+        content = await fs.readJson(filePath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `Failed to parse JSON: ${message}` };
+    }
+    // Validate structure
+    const parseResult = importFileSchema.safeParse(content);
+    if (!parseResult.success) {
+        const issues = parseResult.error.issues
+            .map((issue) => `${issue.path.join('.')}: ${issue.message}`)
+            .join('; ');
+        return { success: false, error: `Validation failed: ${issues}` };
+    }
+    const importData = parseResult.data;
+    // Convert to BacktestThread format
+    const threads = importData.threads.map((t) => convertImportThread(t));
+    return {
+        success: true,
+        name: importData.name,
+        threads,
+    };
+}
+/**
+ * Convert an import thread to a BacktestThread.
+ */
+function convertImportThread(input) {
+    const thread = {
+        project_id: input.project_id,
+        project_name: input.project_name,
+        project_symbol: input.project_symbol,
+        project_categories: input.project_categories,
+        project_description: input.project_description,
+        text: input.text,
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        price_on_fetch: input.price_on_fetch,
+        price_on_eval: input.price_on_eval,
+        citations: input.citations ?? [],
+    };
+    return thread;
+}
+/**
+ * Validate a single thread input (for interactive mode).
+ */
+export function validateThreadInput(input) {
+    const errors = [];
+    if (!input.project_id || input.project_id.trim() === '') {
+        errors.push('project_id is required');
+    }
+    if (!input.project_name || input.project_name.trim() === '') {
+        errors.push('project_name is required');
+    }
+    if (!input.text || input.text.trim() === '') {
+        errors.push('text is required');
+    }
+    if (typeof input.price_on_fetch !== 'number' || input.price_on_fetch <= 0) {
+        errors.push('price_on_fetch must be a positive number');
+    }
+    if (typeof input.price_on_eval !== 'number' || input.price_on_eval <= 0) {
+        errors.push('price_on_eval must be a positive number');
+    }
+    return errors;
+}
+/**
+ * Create a BacktestThread from validated input.
+ */
+export function createThread(input) {
+    return convertImportThread(input);
+}

package/dist/backtest/index.js

@@ -0,0 +1,10 @@
+// Import
+export { importBacktestFile, validateThreadInput, createThread } from './import.js';
+// Storage
+export { DEFAULT_BACKTEST_ID, loadDefaultBacktest } from './storage.js';
+// Fetch
+export { fetchBacktestThreads } from './fetch.js';
+// Runner
+export { runBacktest } from './runner.js';
+// Results
+export { formatConviction, formatPercentage, getDirectionIndicator, formatThreadResult, formatSummary, getAccuracyGrade, buildTextReport, } from './results.js';

package/dist/backtest/results.js

@@ -0,0 +1,113 @@
+/**
+ * Format a number with sign for display.
+ */
+export function formatConviction(value) {
+    const sign = value >= 0 ? '+' : '';
+    const formatted = `${sign}${value.toFixed(2)}%`;
+    return formatted;
+}
+/**
+ * Format a percentage for display.
+ */
+export function formatPercentage(value) {
+    const formatted = `${value.toFixed(1)}%`;
+    return formatted;
+}
+/**
+ * Get direction indicator.
+ */
+export function getDirectionIndicator(conviction) {
+    if (conviction > 0) {
+        return 'bullish';
+    }
+    if (conviction < 0) {
+        return 'bearish';
+    }
+    return 'neutral';
+}
+export function formatThreadResult(result) {
+    if (result.skipped) {
+        return {
+            index: result.thread_index + 1,
+            projectName: result.project_name,
+            predicted: 'SKIP',
+            actual: formatConviction(result.actual_price_change_percent),
+            direction: 'skipped',
+            error: '-',
+            summary: '(skipped)',
+            thread_text: result.thread_text,
+        };
+    }
+    const directionLabel = result.direction_correct ? 'correct' : 'incorrect';
+    return {
+        index: result.thread_index + 1,
+        projectName: result.project_name,
+        predicted: formatConviction(result.predicted_conviction),
+        actual: formatConviction(result.actual_price_change_percent),
+        direction: directionLabel,
+        error: result.absolute_error !== null ? result.absolute_error.toFixed(2) : '-',
+        summary: result.predicted_summary.slice(0, 200) + (result.predicted_summary.length > 200 ? '...' : ''),
+        thread_text: result.thread_text.slice(0, 100) + (result.thread_text.length > 100 ? '...' : ''),
+    };
+}
+export function formatSummary(result) {
+    return {
+        agentName: result.agent_name,
+        backtestId: result.backtest_id,
+        totalThreads: result.total_threads,
+        threadsPredicted: result.threads_predicted,
+        threadsSkipped: result.threads_skipped,
+        directionAccuracy: formatPercentage(result.direction_accuracy),
+        meanAbsoluteError: result.mean_absolute_error.toFixed(2),
+        runAt: new Date(result.run_at).toLocaleString(),
+    };
+}
+/**
+ * Get accuracy grade based on direction accuracy percentage.
+ */
+export function getAccuracyGrade(accuracy) {
+    if (accuracy >= 70) {
+        return { grade: 'A', color: 'green' };
+    }
+    if (accuracy >= 60) {
+        return { grade: 'B', color: 'green' };
+    }
+    if (accuracy >= 50) {
+        return { grade: 'C', color: 'honey' };
+    }
+    if (accuracy >= 40) {
+        return { grade: 'D', color: 'red' };
+    }
+    return { grade: 'F', color: 'red' };
+}
+/**
+ * Build a text report of the backtest results.
+ */
+export function buildTextReport(result) {
+    const lines = [];
+    const summary = formatSummary(result);
+    lines.push(`Backtest Results: ${summary.backtestId}`);
+    lines.push(`Agent: ${summary.agentName}`);
+    lines.push(`Run at: ${summary.runAt}`);
+    lines.push('');
+    lines.push('--- Summary ---');
+    lines.push(`Total threads: ${summary.totalThreads}`);
+    lines.push(`Predictions made: ${summary.threadsPredicted}`);
+    lines.push(`Skipped: ${summary.threadsSkipped}`);
+    lines.push(`Direction accuracy: ${summary.directionAccuracy}`);
+    lines.push(`Mean absolute error: ${summary.meanAbsoluteError}`);
+    lines.push('');
+    lines.push('--- Per-Thread Results ---');
+    for (const threadResult of result.thread_results) {
+        const formatted = formatThreadResult(threadResult);
+        const directionSymbol = formatted.direction === 'correct'
+            ? '[OK]'
+            : formatted.direction === 'skipped'
+                ? '[--]'
+                : '[XX]';
+        lines.push(`#${formatted.index} ${formatted.projectName}: Predicted ${formatted.predicted}, Actual ${formatted.actual} ${directionSymbol}`);
+        lines.push(`\tThread: ${formatted.thread_text}`);
+        lines.push(`\tSummary: ${formatted.summary}`);
+    }
+    return lines.join('\n');
+}

package/dist/backtest/runner.js

@@ -0,0 +1,134 @@
+import { processSignalAndSummarize } from '../agent/analysis.js';
+import { loadMemory } from '@hive-org/sdk';
+import { getAllTools, initializeSkills, getSkillMetadataList, getReadSkillTool, } from '../agent/tools/index.js';
+/**
+ * Run a backtest against an agent configuration.
+ */
+export async function runBacktest(backtest, config, callbacks) {
+    const { agentPath, soulContent, strategyContent, agentName } = config;
+    const threads = backtest.threads;
+    const results = [];
+    // Load agent tools and skills
+    const baseTools = getAllTools();
+    const skillRegistry = await initializeSkills(agentPath);
+    const tools = { ...baseTools };
+    if (skillRegistry.size > 0) {
+        tools['readSkill'] = getReadSkillTool(skillRegistry);
+    }
+    const availableSkills = getSkillMetadataList(skillRegistry) || undefined;
+    // Load memory once (static for backtest)
+    const memory = await loadMemory();
+    for (let i = 0; i < threads.length; i++) {
+        const thread = threads[i];
+        callbacks?.onThreadStart?.(i, threads.length, thread);
+        // Convert BacktestThread to ThreadDto format (without price_on_eval)
+        const threadDto = convertToThreadDto(thread, i);
+        // Run analysis
+        const analysisResult = await processSignalAndSummarize(threadDto, [], // No recent comments in backtest
+        memory, soulContent, strategyContent, tools, availableSkills);
+        // Calculate actual price change
+        const actualPriceChangePercent = calculatePriceChange(thread.price_on_fetch, thread.price_on_eval);
+        // Build result
+        const result = buildThreadResult(i, thread, analysisResult, actualPriceChangePercent);
+        results.push(result);
+        callbacks?.onThreadComplete?.(i, result);
+    }
+    // Calculate summary statistics
+    const runResult = buildRunResult(backtest.metadata.id, agentName, results);
+    return runResult;
+}
+/**
+ * Convert a BacktestThread to ThreadDto format for the agent.
+ * Strips price_on_eval since the agent shouldn't see the outcome.
+ */
+function convertToThreadDto(thread, index) {
+    const dto = {
+        id: `backtest-thread-${index}`,
+        pollen_id: `backtest-pollen-${index}`,
+        project_id: thread.project_id,
+        project_name: thread.project_name,
+        project_categories: thread.project_categories,
+        project_description: thread.project_description,
+        project_symbol: thread.project_symbol,
+        price_on_eval: thread.price_on_eval,
+        text: thread.text,
+        timestamp: thread.timestamp,
+        locked: false,
+        created_at: thread.timestamp,
+        updated_at: thread.timestamp,
+        price_on_fetch: thread.price_on_fetch,
+        // Intentionally omitting price_on_eval - agent should not see outcome
+        citations: thread.citations,
+    };
+    return dto;
+}
+/**
+ * Calculate percentage price change.
+ */
+function calculatePriceChange(priceOnFetch, priceOnEval) {
+    const change = ((priceOnEval - priceOnFetch) / priceOnFetch) * 100;
+    return change;
+}
+/**
+ * Build a thread result from analysis output.
+ */
+function buildThreadResult(index, thread, analysis, actualPriceChangePercent) {
+    if (analysis.skip) {
+        return {
+            thread_index: index,
+            project_id: thread.project_id,
+            project_name: thread.project_name,
+            thread_text: thread.text,
+            predicted_conviction: 0,
+            predicted_summary: '',
+            skipped: true,
+            actual_price_change_percent: actualPriceChangePercent,
+            direction_correct: null,
+            absolute_error: null,
+        };
+    }
+    // Determine direction correctness
+    const predictedDirection = Math.sign(analysis.conviction);
+    const actualDirection = Math.sign(actualPriceChangePercent);
+    const directionCorrect = predictedDirection === actualDirection;
+    // Calculate absolute error
+    const absoluteError = Math.abs(analysis.conviction - actualPriceChangePercent);
+    return {
+        thread_index: index,
+        project_id: thread.project_id,
+        project_name: thread.project_name,
+        thread_text: thread.text,
+        predicted_conviction: analysis.conviction,
+        predicted_summary: analysis.summary,
+        skipped: false,
+        actual_price_change_percent: actualPriceChangePercent,
+        direction_correct: directionCorrect,
+        absolute_error: absoluteError,
+    };
+}
+/**
+ * Build the final run result with summary statistics.
+ */
+function buildRunResult(backtestId, agentName, results) {
+    const totalThreads = results.length;
+    const predictedResults = results.filter((r) => !r.skipped);
+    const threadsPredicted = predictedResults.length;
+    const threadsSkipped = totalThreads - threadsPredicted;
+    // Calculate direction accuracy
+    const correctDirections = predictedResults.filter((r) => r.direction_correct === true).length;
+    const directionAccuracy = threadsPredicted > 0 ? (correctDirections / threadsPredicted) * 100 : 0;
+    // Calculate mean absolute error
+    const totalError = predictedResults.reduce((sum, r) => sum + (r.absolute_error ?? 0), 0);
+    const meanAbsoluteError = threadsPredicted > 0 ? totalError / threadsPredicted : 0;
+    return {
+        backtest_id: backtestId,
+        agent_name: agentName,
+        run_at: new Date().toISOString(),
+        thread_results: results,
+        total_threads: totalThreads,
+        threads_predicted: threadsPredicted,
+        threads_skipped: threadsSkipped,
+        direction_accuracy: directionAccuracy,
+        mean_absolute_error: meanAbsoluteError,
+    };
+}

package/dist/backtest/storage.js

@@ -0,0 +1,11 @@
+import { DEFAULT_BACKTEST_DATA } from './default-backtest-data.js';
+/**
+ * ID for the bundled default backtest dataset.
+ */
+export const DEFAULT_BACKTEST_ID = 'default';
+/**
+ * Load the bundled default backtest dataset.
+ */
+export function loadDefaultBacktest() {
+    return DEFAULT_BACKTEST_DATA;
+}

package/dist/backtest/types.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/create/ai-generate.js

@@ -0,0 +1,126 @@
+import { streamText } from 'ai';
+import { buildLanguageModel } from '../../shared/config/ai-providers.js';
+import { SOUL_PRESETS, STRATEGY_PRESETS, buildSoulMarkdown, buildStrategyMarkdown, } from './presets/index.js';
+function buildPresetExamples() {
+    const soulExamples = SOUL_PRESETS.map((p) => buildSoulMarkdown('ExampleAgent', 'example bio text for reference', p, '')).join('\n---\n');
+    const strategyExamples = STRATEGY_PRESETS.map((p) => buildStrategyMarkdown('ExampleAgent', p)).join('\n---\n');
+    return `${soulExamples}\n\n===\n\n${strategyExamples}`;
+}
+const PRESET_EXAMPLES = buildPresetExamples();
+export function streamSoul(providerId, apiKey, agentName, bio, avatarUrl, personality, tone, voiceStyle, tradingStyle, sectors, sentiment, timeframes, feedback) {
+    const feedbackLine = feedback
+        ? `\n\nThe user gave this feedback on the previous draft. Adjust accordingly:\n"${feedback}"`
+        : '';
+    const sectorsLine = sectors.length > 0 ? sectors.join(', ') : 'all categories';
+    const timeframesLine = timeframes.length > 0 ? timeframes.join(', ') : 'all timeframes';
+    const identityContext = `Personality: ${personality}
+Tone: ${tone}
+Voice style: ${voiceStyle}
+Trading style: ${tradingStyle}
+Sectors: ${sectorsLine}
+Sentiment: ${sentiment}
+Preferred timeframes: ${timeframesLine}`;
+    const prompt = `You are a creative writer designing an AI agent's personality profile for a crypto trading bot called "${agentName}".
+
+The agent's bio is: "${bio}"
+${avatarUrl ? `Avatar URL: ${avatarUrl}` : 'No avatar URL provided.'}
+
+Identity traits:
+${identityContext}
+
+Context — Hive is a prediction game for AI agents:
+- Signals appear in cells (e.g. c/ethereum, c/bitcoin) when noteworthy crypto events happen.
+- Agents submit a percentage prediction (predicted price change over 3 hours) and a short reasoning.
+- Threads resolve at T+3h. Correct-direction predictions earn honey (the ranking currency); wrong-direction predictions earn wax.
+- Early predictions are worth dramatically more than late ones (steep time bonus decay).
+- Streaks track consecutive correct-direction predictions. Skipping a thread carries no penalty and does not break streaks.
+- Agents are ranked on a leaderboard by total honey.
+
+Generate a SOUL.md file for this agent. The SOUL.md defines who the agent IS — their personality, voice, quirks, opinions, and how they post. The personality should be aware that the agent operates in this prediction game — their voice should reflect how they approach predictions, risk, and competition. Use the identity traits above to shape the personality, tone, and writing style.
+
+CRITICAL: Output ONLY valid markdown matching this exact structure. No extra commentary.
+
+The first line MUST be: # Agent: ${agentName}
+
+Here are reference examples of well-crafted SOUL.md files:
+---
+${PRESET_EXAMPLES.split('===')[0]}
+---
+
+Use these as style/quality references but create something UNIQUE based on the agent's name, bio, and identity traits.${feedbackLine}`;
+    const model = buildLanguageModel(providerId, apiKey, 'generation');
+    const result = streamText({
+        model,
+        prompt,
+        maxOutputTokens: 1500,
+    });
+    return result.textStream;
+}
+export function streamStrategy(providerId, apiKey, agentName, bio, personality, tone, voiceStyle, tradingStyle, sectors, sentiment, timeframes, feedback) {
+    const feedbackLine = feedback
+        ? `\n\nThe user gave this feedback on the previous draft. Adjust accordingly:\n"${feedback}"`
+        : '';
+    const sectorsLine = sectors.length > 0 ? sectors.join(', ') : 'all categories';
+    const timeframesLine = timeframes.length > 0 ? timeframes.join(', ') : 'all timeframes';
+    const identityContext = `Personality: ${personality}
+Tone: ${tone}
+Voice style: ${voiceStyle}
+Trading style: ${tradingStyle}
+Sectors: ${sectorsLine}
+Sentiment: ${sentiment}
+Preferred timeframes: ${timeframesLine}`;
+    const prompt = `You are designing a prediction strategy profile for a crypto trading bot called "${agentName}".
+
+The agent's bio is: "${bio}"
+
+Identity traits:
+${identityContext}
+
+Context — Hive game mechanics that the strategy should account for:
+- Agents predict the percentage price change of a crypto asset over a 3-hour window.
+- Conviction is a number (e.g. 2.5 for +2.5%, -3.0 for -3.0%, 0 for neutral).
+- Correct-direction predictions earn honey (the primary ranking currency). Wrong-direction predictions earn wax (not a penalty, but doesn't help ranking).
+- Direction matters more than magnitude for earning honey, though closer magnitude predictions earn more.
+- Early predictions earn dramatically more honey due to steep time bonus decay — speed matters.
+- Consecutive correct-direction predictions build a streak (tracked on profile). Skipping does not break streaks.
+- Skipping is a valid strategy — no penalty, no streak break. Knowing when to sit out is a skill.
+- Agents are ranked on a leaderboard by total honey.
+
+Generate a STRATEGY.md file. The STRATEGY.md defines HOW the agent makes predictions — their method, sector focus, and decision framework. The strategy should reflect the agent's personality and tone, and should address the game mechanics above (e.g. when to skip, how aggressive to be with timing, how to calibrate conviction magnitude).
+
+CRITICAL: Output ONLY valid markdown matching this exact structure. No extra commentary.
+
+The first line MUST be: # Prediction Strategy: ${agentName}
+
+Required sections with EXACT headers:
+## Philosophy
+## Signal Interpretation
+- Method: (must be one of: technical, fundamental, sentiment, onchain, macro)
+- Primary indicators: (list key indicators)
+## Sentiment
+- Bias: ${sentiment}
+## Sector Focus
+- Sectors: ${sectorsLine}
+- Avoid: (sectors to avoid)
+## Timeframe
+- Active timeframes: ${timeframesLine}
+(Explain why these timeframes suit the agent's style. Mention that the agent skips signals outside these timeframes.)
+## Decision Framework
+1. (first step)
+2. (second step)
+3. (third step)
+
+Here are reference examples of well-crafted STRATEGY.md files:
+---
+${PRESET_EXAMPLES.split('===')[1] || ''}
+---
+
+Create something UNIQUE based on the agent's name, bio, and identity traits.${feedbackLine}`;
+    const model = buildLanguageModel(providerId, apiKey, 'generation');
+    const result = streamText({
+        model,
+        prompt,
+        maxOutputTokens: 1200,
+    });
+    return result.textStream;
+}

package/dist/commands/create/commands/index.js

@@ -0,0 +1,10 @@
+import { render } from 'ink';
+import React from 'react';
+import { showWelcome } from '../../shared/welcome.js';
+import { CreateApp } from '../ui/CreateApp.js';
+export const createCommand = async (argv) => {
+    const projectName = process.argv[3];
+    await showWelcome();
+    const { waitUntilExit } = render(React.createElement(CreateApp, { initialName: projectName }));
+    await waitUntilExit();
+};

package/dist/commands/create/generate.js

@@ -0,0 +1,73 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export async function scaffoldProject(projectName, provider, apiKey, soulContent, strategyContent, callbacks) {
+    // Validate project name to prevent path traversal / command injection
+    if (!/^[a-zA-Z0-9_-]+$/.test(projectName)) {
+        callbacks.onError('Project name can only contain letters, numbers, dashes, and underscores.');
+        return;
+    }
+    const agentsDir = path.join(os.homedir(), '.hive', 'agents');
+    const projectDir = path.join(agentsDir, projectName);
+    // Ensure resolved path is still inside ~/.hive/agents/
+    const normalizedProjectDir = path.resolve(projectDir);
+    const normalizedAgentsDir = path.resolve(agentsDir);
+    if (!normalizedProjectDir.startsWith(normalizedAgentsDir + path.sep)) {
+        callbacks.onError('Invalid project name: path traversal detected.');
+        return;
+    }
+    if (await fs.pathExists(projectDir)) {
+        callbacks.onError(`Directory ${normalizedProjectDir} already exists. Run "npx @zhive/cli@latest create" again with a different name.`);
+        return;
+    }
+    // 1. Create directory
+    callbacks.onStep('Creating project directory');
+    await fs.ensureDir(projectDir);
+    // 2. Write SOUL.md and STRATEGY.md
+    callbacks.onStep('Writing personality files');
+    await fs.writeFile(path.join(projectDir, 'SOUL.md'), soulContent, 'utf-8');
+    await fs.writeFile(path.join(projectDir, 'STRATEGY.md'), strategyContent, 'utf-8');
+    const seedMemory = `# Memory
+
+## Key Learnings
+
+(none yet)
+
+## Market Observations
+
+(none yet)
+
+## Session Notes
+
+(none yet)
+`;
+    await fs.writeFile(path.join(projectDir, 'MEMORY.md'), seedMemory, 'utf-8');
+    // 3. Write .env
+    callbacks.onStep('Writing environment file');
+    const envContent = `${provider.envVar}="${apiKey}"
+`;
+    await fs.writeFile(path.join(projectDir, '.env'), envContent, { encoding: 'utf-8', mode: 0o600 });
+    // 4. Write minimal package.json — no deps needed, npx fetches @zhive/agent@latest on every run
+    callbacks.onStep('Configuring project');
+    const packageJson = {
+        name: `hive-agent-${projectName}`,
+        private: true,
+        type: 'module',
+        scripts: {
+            start: 'npx @zhive/cli@latest start',
+        },
+    };
+    await fs.writeJson(path.join(projectDir, 'package.json'), packageJson, { spaces: 2 });
+    // 5. Copy default skills
+    callbacks.onStep('Installing default skills');
+    const templateSkillsDir = path.resolve(__dirname, '../../templates/skills');
+    const projectSkillsDir = path.join(projectDir, 'skills');
+    const templateSkillsExist = await fs.pathExists(templateSkillsDir);
+    if (templateSkillsExist) {
+        await fs.copy(templateSkillsDir, projectSkillsDir);
+    }
+    callbacks.onDone(normalizedProjectDir);
+}