@zhive/cli 0.5.0

package/dist/shared/agent/skills/skill-parser.js

@@ -0,0 +1,167 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { extractErrorMessage } from '../utils.js';
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ * Expected format:
+ * ---
+ * name: skill-name
+ * description: Skill description
+ * ---
+ * Body content...
+ */
+export function parseFrontmatter(content) {
+    const trimmed = content.trim();
+    if (!trimmed.startsWith('---')) {
+        throw new Error('SKILL.md must start with YAML frontmatter (---)');
+    }
+    const endIndex = trimmed.indexOf('---', 3);
+    if (endIndex === -1) {
+        throw new Error('SKILL.md frontmatter is not closed (missing closing ---)');
+    }
+    const frontmatterContent = trimmed.slice(3, endIndex).trim();
+    const body = trimmed.slice(endIndex + 3).trim();
+    const metadata = {
+        name: '',
+        description: '',
+    };
+    const lines = frontmatterContent.split('\n');
+    let currentKey = null;
+    let currentValue = '';
+    for (const line of lines) {
+        const trimmedLine = line.trim();
+        if (trimmedLine.startsWith('name:')) {
+            if (currentKey !== null) {
+                setMetadataField(metadata, currentKey, currentValue.trim());
+            }
+            currentKey = 'name';
+            currentValue = trimmedLine.slice(5).trim();
+        }
+        else if (trimmedLine.startsWith('description:')) {
+            if (currentKey !== null) {
+                setMetadataField(metadata, currentKey, currentValue.trim());
+            }
+            currentKey = 'description';
+            const value = trimmedLine.slice(12).trim();
+            if (value === '>' || value === '|') {
+                currentValue = '';
+            }
+            else {
+                currentValue = value;
+            }
+        }
+        else if (trimmedLine.startsWith('compatibility:')) {
+            if (currentKey !== null) {
+                setMetadataField(metadata, currentKey, currentValue.trim());
+            }
+            currentKey = 'compatibility';
+            const value = trimmedLine.slice(14).trim();
+            if (value === '>' || value === '|') {
+                currentValue = '';
+            }
+            else {
+                currentValue = value;
+            }
+        }
+        else if (currentKey !== null && (line.startsWith('  ') || line.startsWith('\t'))) {
+            currentValue += ' ' + trimmedLine;
+        }
+    }
+    if (currentKey !== null) {
+        setMetadataField(metadata, currentKey, currentValue.trim());
+    }
+    if (metadata.name === '') {
+        throw new Error('SKILL.md frontmatter must include "name" field');
+    }
+    if (metadata.description === '') {
+        throw new Error('SKILL.md frontmatter must include "description" field');
+    }
+    return { metadata, body };
+}
+function setMetadataField(metadata, key, value) {
+    if (key === 'name') {
+        metadata.name = value;
+    }
+    else if (key === 'description') {
+        metadata.description = value;
+    }
+    else if (key === 'compatibility') {
+        const truncatedValue = value.slice(0, 500);
+        metadata.compatibility = truncatedValue;
+    }
+}
+/**
+ * Check if a directory exists.
+ */
+async function directoryExists(dirPath) {
+    try {
+        const stat = await fs.stat(dirPath);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a file exists.
+ */
+async function fileExists(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Discover and load a single skill from a directory.
+ * Skills are knowledge-only documents (no tools).
+ */
+export async function loadSkill(skillPath) {
+    const skillMdPath = path.join(skillPath, 'SKILL.md');
+    const exists = await fileExists(skillMdPath);
+    if (!exists) {
+        return null;
+    }
+    try {
+        const content = await fs.readFile(skillMdPath, 'utf-8');
+        const { metadata, body } = parseFrontmatter(content);
+        const id = path.basename(skillPath);
+        const skill = {
+            id,
+            path: skillPath,
+            metadata,
+            body,
+        };
+        return skill;
+    }
+    catch (err) {
+        const message = extractErrorMessage(err);
+        console.error(`Failed to load skill from ${skillPath}: ${message}`);
+        return null;
+    }
+}
+/**
+ * Discover all skills in a directory.
+ * Each subdirectory containing SKILL.md is treated as a skill.
+ */
+export async function discoverSkills(skillsDir) {
+    const exists = await directoryExists(skillsDir);
+    if (!exists) {
+        return [];
+    }
+    const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const skillPath = path.join(skillsDir, entry.name);
+        const skill = await loadSkill(skillPath);
+        if (skill !== null) {
+            skills.push(skill);
+        }
+    }
+    return skills;
+}

package/dist/shared/agent/skills/skill-parser.test.js

@@ -0,0 +1,190 @@
+import { describe, it, expect, vi } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import { parseFrontmatter, discoverSkills, loadSkill } from './skill-parser.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURES_DIR = path.join(__dirname, '../../../../__fixtures__/mock-hive');
+function getFixturePath(...segments) {
+    return path.join(FIXTURES_DIR, ...segments);
+}
+describe('parseFrontmatter', () => {
+    it('parses valid frontmatter with name and description', () => {
+        const content = `---
+name: test-skill
+description: A test skill for testing
+---
+Body content here.`;
+        const result = parseFrontmatter(content);
+        expect(result.metadata.name).toBe('test-skill');
+        expect(result.metadata.description).toBe('A test skill for testing');
+        expect(result.body).toBe('Body content here.');
+    });
+    it('parses multiline description using YAML block indicator', () => {
+        const content = `---
+name: multi-line-skill
+description: >
+  This is a multiline
+  description that spans
+  multiple lines
+---
+Skill instructions here.`;
+        const result = parseFrontmatter(content);
+        expect(result.metadata.name).toBe('multi-line-skill');
+        expect(result.metadata.description).toContain('This is a multiline');
+        expect(result.metadata.description).toContain('description that spans');
+        expect(result.body).toBe('Skill instructions here.');
+    });
+    it('parses compatibility field when present', () => {
+        const content = `---
+name: compat-skill
+description: Skill with compatibility
+compatibility: Requires Node 18+
+---
+Body.`;
+        const result = parseFrontmatter(content);
+        expect(result.metadata.name).toBe('compat-skill');
+        expect(result.metadata.description).toBe('Skill with compatibility');
+        expect(result.metadata.compatibility).toBe('Requires Node 18+');
+    });
+    it('truncates compatibility to 500 characters', () => {
+        const longCompat = 'x'.repeat(600);
+        const content = `---
+name: long-compat
+description: Test
+compatibility: ${longCompat}
+---
+Body.`;
+        const result = parseFrontmatter(content);
+        expect(result.metadata.compatibility?.length).toBe(500);
+    });
+    it('throws error when frontmatter does not start with ---', () => {
+        const content = `name: invalid
+description: No opening delimiter
+---
+Body.`;
+        expect(() => parseFrontmatter(content)).toThrow('must start with YAML frontmatter');
+    });
+    it('throws error when frontmatter is not closed', () => {
+        const content = `---
+name: unclosed
+description: Missing closing delimiter
+Body.`;
+        expect(() => parseFrontmatter(content)).toThrow('not closed');
+    });
+    it('throws error when name field is missing', () => {
+        const content = `---
+description: Missing name
+---
+Body.`;
+        expect(() => parseFrontmatter(content)).toThrow('must include "name" field');
+    });
+    it('throws error when description field is missing', () => {
+        const content = `---
+name: no-description
+---
+Body.`;
+        expect(() => parseFrontmatter(content)).toThrow('must include "description" field');
+    });
+    it('handles empty body content', () => {
+        const content = `---
+name: empty-body
+description: Skill with no body
+---`;
+        const result = parseFrontmatter(content);
+        expect(result.metadata.name).toBe('empty-body');
+        expect(result.body).toBe('');
+    });
+    it('handles whitespace around content', () => {
+        const content = `
+---
+name: whitespace-skill
+description: Handles whitespace
+---
+
+  Body with whitespace.
+`;
+        const result = parseFrontmatter(content);
+        expect(result.metadata.name).toBe('whitespace-skill');
+        expect(result.body).toBe('Body with whitespace.');
+    });
+});
+describe('discoverSkills', () => {
+    it('returns empty array for non-existent directory', async () => {
+        const nonExistentPath = getFixturePath('agents', 'non-existent', 'skills');
+        const result = await discoverSkills(nonExistentPath);
+        expect(result).toEqual([]);
+    });
+    it('returns empty array for empty skills directory', async () => {
+        const emptySkillsPath = getFixturePath('agents', 'empty-agent', 'skills');
+        const result = await discoverSkills(emptySkillsPath);
+        expect(result).toEqual([]);
+    });
+    it('returns empty array for agent without skills directory', async () => {
+        const noSkillsDirPath = getFixturePath('agents', 'agent-no-skills', 'skills');
+        const result = await discoverSkills(noSkillsDirPath);
+        expect(result).toEqual([]);
+    });
+    it('discovers valid skills from subdirectories', async () => {
+        const skillsPath = getFixturePath('agents', 'test-agent', 'skills');
+        const result = await discoverSkills(skillsPath);
+        expect(result).toHaveLength(2);
+        const skillIds = result.map((s) => s.id).sort();
+        expect(skillIds).toEqual(['skill-with-compat', 'valid-skill']);
+    });
+    it('loads skill metadata correctly', async () => {
+        const skillsPath = getFixturePath('agents', 'test-agent', 'skills');
+        const result = await discoverSkills(skillsPath);
+        const validSkill = result.find((s) => s.id === 'valid-skill');
+        expect(validSkill).toBeDefined();
+        expect(validSkill?.metadata.name).toBe('Valid Skill');
+        expect(validSkill?.metadata.description).toBe('A valid test skill for testing');
+        expect(validSkill?.body).toBe('This is the body content of the valid skill.');
+    });
+    it('loads skill with compatibility field', async () => {
+        const skillsPath = getFixturePath('agents', 'test-agent', 'skills');
+        const result = await discoverSkills(skillsPath);
+        const compatSkill = result.find((s) => s.id === 'skill-with-compat');
+        expect(compatSkill).toBeDefined();
+        expect(compatSkill?.metadata.name).toBe('Skill With Compatibility');
+        expect(compatSkill?.metadata.description).toBe('A skill that has compatibility requirements');
+        expect(compatSkill?.metadata.compatibility).toBe('Requires Node 18+');
+    });
+});
+describe('loadSkill', () => {
+    it('returns null when skill directory does not exist', async () => {
+        const nonExistentPath = getFixturePath('agents', 'test-agent', 'skills', 'non-existent');
+        const result = await loadSkill(nonExistentPath);
+        expect(result).toBeNull();
+    });
+    it('loads and parses valid SKILL.md', async () => {
+        const skillPath = getFixturePath('agents', 'test-agent', 'skills', 'valid-skill');
+        const result = await loadSkill(skillPath);
+        expect(result).not.toBeNull();
+        expect(result?.id).toBe('valid-skill');
+        expect(result?.path).toBe(skillPath);
+        expect(result?.metadata.name).toBe('Valid Skill');
+        expect(result?.metadata.description).toBe('A valid test skill for testing');
+        expect(result?.body).toBe('This is the body content of the valid skill.');
+    });
+    it('loads skill with compatibility field', async () => {
+        const skillPath = getFixturePath('agents', 'test-agent', 'skills', 'skill-with-compat');
+        const result = await loadSkill(skillPath);
+        expect(result).not.toBeNull();
+        expect(result?.id).toBe('skill-with-compat');
+        expect(result?.metadata.name).toBe('Skill With Compatibility');
+        expect(result?.metadata.compatibility).toBe('Requires Node 18+');
+        expect(result?.body).toBe('This skill has compatibility requirements.');
+    });
+    it('returns null for directory without SKILL.md', async () => {
+        const emptyDirPath = getFixturePath('agents', 'empty-agent', 'skills');
+        const result = await loadSkill(emptyDirPath);
+        expect(result).toBeNull();
+    });
+    it('returns null and logs error for invalid frontmatter', async () => {
+        const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const agentNoSkillsPath = getFixturePath('agents', 'agent-no-skills');
+        const result = await loadSkill(agentNoSkillsPath);
+        expect(result).toBeNull();
+        consoleSpy.mockRestore();
+    });
+});

package/dist/shared/agent/skills/types.js

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

package/dist/shared/agent/tools/edit-section.js

@@ -0,0 +1,60 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { extractErrorMessage } from '../utils.js';
+export function replaceSection(fileContent, heading, newContent) {
+    const lines = fileContent.split('\n');
+    const headingLine = `## ${heading}`;
+    let startIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === headingLine) {
+            startIdx = i;
+            break;
+        }
+    }
+    if (startIdx === -1) {
+        throw new Error(`Section "## ${heading}" not found in file.`);
+    }
+    let endIdx = lines.length;
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith('## ') || trimmed.startsWith('# ')) {
+            endIdx = i;
+            break;
+        }
+    }
+    const before = lines.slice(0, startIdx + 1);
+    const after = lines.slice(endIdx);
+    const trimmedContent = newContent.trim();
+    const newSection = ['', ...trimmedContent.split('\n'), ''];
+    const result = [...before, ...newSection, ...after].join('\n');
+    return result;
+}
+export const editSectionTool = tool({
+    description: 'Edit a section of SOUL.md or STRATEGY.md. Only call AFTER user confirms.',
+    inputSchema: z.object({
+        file: z.enum(['SOUL.md', 'STRATEGY.md']),
+        section: z.string().describe('Exact ## heading name, e.g. "Personality", "Conviction Style"'),
+        content: z.string().describe('New content for the section (without the ## heading line)'),
+    }),
+    execute: async ({ file, section, content }) => {
+        const filePath = path.join(process.cwd(), file);
+        let fileContent;
+        try {
+            fileContent = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            return `Error: ${file} not found in current directory.`;
+        }
+        try {
+            const updated = replaceSection(fileContent, section, content);
+            await fs.writeFile(filePath, updated, 'utf-8');
+            return `Updated "${section}" section in ${file}.`;
+        }
+        catch (err) {
+            const message = extractErrorMessage(err);
+            return `Error: ${message}`;
+        }
+    },
+});

package/dist/shared/agent/tools/execute-skill-tool.js

@@ -0,0 +1,134 @@
+import { tool } from 'ai';
+import * as ai from 'ai';
+import { z } from 'zod';
+import { wrapAISDK } from 'langsmith/experimental/vercel';
+import { getAllTools } from './index.js';
+const { ToolLoopAgent } = wrapAISDK(ai);
+let _subagentUsageLog = [];
+export function clearSubagentUsage() {
+    _subagentUsageLog = [];
+}
+export function getSubagentUsage() {
+    return [..._subagentUsageLog];
+}
+function logSubagentUsage(usage) {
+    _subagentUsageLog.push(usage);
+}
+const DEFAULT_SUBAGENT_CONFIG = {
+    maxOutputTokens: 2048,
+    timeoutMs: 60_000, // 1 minute
+};
+// ─── Input Schema ─────────────────────────────────────
+const skillExecutionInputSchema = z.object({
+    skillId: z.string().describe('The skill ID to execute'),
+    task: z.string().describe('The task/instructions for the subagent to perform'),
+    context: z.string().optional().describe('Additional context (e.g., project ID, data)'),
+});
+// ─── System Prompt Template ───────────────────────────
+function buildSubagentSystemPrompt(skill) {
+    const systemPrompt = `You are a specialized agent with the following expertise:
+
+${skill.body}
+
+Use your expertise and available tools to complete the task given to you.`;
+    return systemPrompt;
+}
+/**
+ * Create a tool that executes a skill as a subagent.
+ * The subagent has access to all tools and uses the skill's body as instructions.
+ * Returns the subagent's freeform text analysis.
+ */
+export function createExecuteSkillTool(skillRegistry, config) {
+    const subagentConfig = {
+        ...DEFAULT_SUBAGENT_CONFIG,
+        ...config.subagentConfig,
+    };
+    const executeSkillTool = tool({
+        description: "Execute a skill as a specialized subagent to perform analysis. The subagent has access to tools and uses the skill's expertise to analyze the project. Returns the subagent's analysis as text.",
+        inputSchema: skillExecutionInputSchema,
+        execute: async ({ skillId, task, context }) => {
+            const skill = skillRegistry.get(skillId);
+            // ── Handle skill not found ──
+            if (skill === undefined) {
+                const availableIds = Array.from(skillRegistry.keys());
+                if (availableIds.length === 0) {
+                    return `Error: Skill "${skillId}" not found. No skills are currently available.`;
+                }
+                const idList = availableIds.join(', ');
+                return `Error: Skill "${skillId}" not found. Available skills: ${idList}`;
+            }
+            // ── Handle empty skill body ──
+            if (!skill.body || skill.body.trim().length === 0) {
+                return `Error: Skill "${skillId}" has no instructions. Cannot execute.`;
+            }
+            // ── Build subagent ──
+            const systemPrompt = buildSubagentSystemPrompt(skill);
+            const tools = getAllTools();
+            const userPrompt = context
+                ? `${task}\n\nContext: ${context}\n\nCurrent Time: ${new Date().toISOString()}`
+                : task;
+            try {
+                // ── Run subagent with timeout ──
+                const subagentPromise = runSubagent({
+                    model: config.model,
+                    systemPrompt,
+                    userPrompt,
+                    tools,
+                    maxOutputTokens: subagentConfig.maxOutputTokens,
+                });
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => {
+                        reject(new Error(`Subagent execution timed out after ${subagentConfig.timeoutMs}ms`));
+                    }, subagentConfig.timeoutMs);
+                });
+                const result = await Promise.race([subagentPromise, timeoutPromise]);
+                // ── Log usage ──
+                logSubagentUsage({
+                    skillId,
+                    inputTokens: result.usage.inputTokens,
+                    outputTokens: result.usage.outputTokens,
+                    cacheReadTokens: result.usage.cacheReadTokens,
+                    cacheWriteTokens: result.usage.cacheWriteTokens,
+                    toolCalls: result.usage.toolCalls,
+                    toolNames: result.usage.toolNames,
+                });
+                // ── Format output ──
+                if (!result.text || result.text.trim().length === 0) {
+                    return `## ${skill.metadata.name} Analysis\n\nNo analysis produced by subagent.`;
+                }
+                const output = `## ${skill.metadata.name} Analysis\n\n${result.text}`;
+                return output;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return `Error executing skill "${skillId}": ${message}`;
+            }
+        },
+    });
+    return executeSkillTool;
+}
+async function runSubagent({ model, systemPrompt, userPrompt, tools, maxOutputTokens, }) {
+    const agent = new ToolLoopAgent({
+        model,
+        instructions: systemPrompt,
+        tools,
+        maxOutputTokens,
+    });
+    const res = await agent.generate({ prompt: userPrompt });
+    // ── Extract usage ──
+    const toolCalls = res.steps.flatMap((s) => s.toolCalls);
+    const toolNames = toolCalls.map((tc) => tc.toolName);
+    const usage = {
+        inputTokens: res.totalUsage?.inputTokens ?? 0,
+        outputTokens: res.totalUsage?.outputTokens ?? 0,
+        cacheReadTokens: res.totalUsage?.inputTokenDetails?.cacheReadTokens ?? 0,
+        cacheWriteTokens: res.totalUsage?.inputTokenDetails?.cacheWriteTokens ?? 0,
+        toolCalls: toolCalls.length,
+        toolNames,
+    };
+    const result = {
+        text: res.text ?? '',
+        usage,
+    };
+    return result;
+}

package/dist/shared/agent/tools/fetch-rules.js

@@ -0,0 +1,22 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { extractErrorMessage } from '../utils.js';
+const RULES_URL = 'https://hive.z3n.dev/RULES.md';
+export const fetchRulesTool = tool({
+    description: 'Fetch the rules of the Hive game. Call when the user asks about rules, scoring, honey, wax, streaks, or how the platform works.',
+    inputSchema: z.object({}),
+    execute: async () => {
+        try {
+            const response = await fetch(RULES_URL);
+            if (!response.ok) {
+                return `Error: failed to fetch rules (HTTP ${response.status}).`;
+            }
+            const rules = await response.text();
+            return rules;
+        }
+        catch (err) {
+            const message = extractErrorMessage(err);
+            return `Error: could not reach Hive to fetch rules. ${message}`;
+        }
+    },
+});

package/dist/shared/agent/tools/formatting.js

@@ -0,0 +1,48 @@
+/**
+ * Shared formatting utilities for agent tool output.
+ */
+import { extractErrorMessage } from '../utils.js';
+/**
+ * Standardised error message for tool catch blocks.
+ */
+export function formatToolError(err, context) {
+    const message = extractErrorMessage(err);
+    const result = `Error ${context}: ${message}`;
+    return result;
+}
+/**
+ * Returns '+' for non-negative values, '' for negative (the minus sign is already present).
+ */
+export function signPrefix(value) {
+    const prefix = value >= 0 ? '+' : '';
+    return prefix;
+}
+/**
+ * Truncate a timeseries array for display, keeping head and tail with a `null` gap in between.
+ * Returns the original array unchanged if it fits within `maxDisplay`.
+ */
+export function truncateTimeseries(data, maxDisplay = 20, headCount = 5, tailCount = 10) {
+    if (data.length <= maxDisplay) {
+        return data;
+    }
+    const truncated = [...data.slice(0, headCount), null, ...data.slice(-tailCount)];
+    return truncated;
+}
+/**
+ * Label for the truncation gap (e.g. `"... (42 more points) ..."`).
+ */
+export function truncationLabel(totalLength, shownCount) {
+    const hidden = totalLength - shownCount;
+    const label = `... (${hidden} more) ...`;
+    return label;
+}
+/**
+ * Format a period-change percentage from first → last value.
+ * Returns e.g. `"Period change: +12.34%"`.
+ */
+export function formatPeriodChange(firstValue, lastValue) {
+    const changePercent = ((lastValue - firstValue) / firstValue) * 100;
+    const sign = signPrefix(changePercent);
+    const result = `Period change: ${sign}${changePercent.toFixed(2)}%`;
+    return result;
+}