@johpaz/hive 1.1.0

package/packages/skills/src/bundled/memory/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: memory
+description: "Store and retrieve persistent information in long-term memory"
+version: 1.0.0
+author: Hive Team
+icon: "🧠"
+category: system
+permissions:
+  - memory_read
+  - memory_write
+dependencies: []
+tools: [memory, memory_write, memory_read, memory_list, memory_search, memory_delete]
+---
+
+# Memory Skill
+
+Esta skill permite al agente mantener una memoria persistente a largo plazo, permitiendo recordar datos entre diferentes sesiones y conversaciones.
+
+## Herramientas Disponibles
+
+- `memory_write`: Almacena información importante (hechos, preferencias, contexto).
+- `memory_read`: Recupera una entrada de memoria por su título.
+- `memory_list`: Lista todos los títulos de las entradas guardadas.
+- `memory_search`: Busca en el contenido de la memoria usando una consulta de texto.
+- `memory_delete`: Elimina una entrada de memoria específica.
+
+## Ejemplos de Uso
+
+### Guardar una preferencia del usuario
+```javascript
+memory_write({ title: "Tecnologías", content: "El usuario prefiere TypeScript y Bun" })
+```
+
+### Buscar información relevante
+```javascript
+memory_search({ query: "Preferencias de desarrollo" })
+```
+
+## Mejores Prácticas
+- **Títulos Descriptivos**: Usa títulos únicos y claros para facilitar la recuperación directa.
+- **Actualización**: Si la información cambia, sobrescribe la entrada con el mismo título.
+- **Privacidad**: Evita guardar información sensible o contraseñas en la memoria persistente.

package/packages/skills/src/bundled/project_management/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: project_management
+description: "Track and manage multi-step project tasks and progress"
+version: 1.0.0
+author: Hive Team
+icon: "📊"
+category: projects
+permissions: []
+dependencies: []
+tools: [project_start, project_update, project_done, project_fail]
+---
+
+# Project Management Skill
+
+Esta skill permite al agente realizar un seguimiento detallado de tareas complejas que requieren múltiples pasos, informando sobre el progreso y el estado final.
+
+## Herramientas Disponibles
+
+- `project_start`: Inicia el seguimiento de una tarea multi-paso.
+- `project_update`: Actualiza el progreso de una tarea en curso.
+- `project_done`: Marca una tarea como completada exitosamente.
+- `project_fail`: Marca una tarea como fallida por error irrecuperable.
+
+## Mejores Prácticas
+- **Actualizaciones Frecuentes**: Informa sobre hitos importantes durante la ejecución de tareas largas.
+- **Claridad en Errores**: Si una tarea falla, proporciona un motivo claro y detallado en `project_fail`.

package/packages/skills/src/bundled/shell/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: shell
+description: "Execute shell commands safely with allowlist control"
+version: 1.0.0
+author: Hive Team
+icon: "💻"
+category: system
+permissions:
+  - shell_exec
+dependencies: []
+tools: [shell, exec, terminal]
+requirements:
+  bins: [bash, sh]
+---
+
+# Shell Skill
+
+Esta skill permite al agente ejecutar comandos en la terminal de forma segura y controlada.
+
+## Herramientas Disponibles
+
+- `exec`: Ejecuta un comando básico sujeto a listas de permisos (allowlist/denylist). Recomendado para tareas simples.
+- `terminal`: Ejecuta comandos directamente en la shell (bash/zsh/cmd). Útil para operaciones de Git, scripts de npm o comandos complejos que requieren mayor flexibilidad.
+
+## Parámetros de Herramientas
+
+### exec
+- `command` (requerido): El comando a ejecutar.
+- `timeout` (opcional): Tiempo de espera en segundos (por defecto: 30).
+
+### terminal
+- `command` (requerido): El comando a ejecutar.
+- `cwd` (opcional): Directorio de trabajo.
+- `timeoutSeconds` (opcional): Tiempo de espera en segundos (por defecto: 60).
+
+## Seguridad
+- `exec` está limitado por la configuración de seguridad de Hive.
+- `terminal` permite una ejecución más directa pero registra todas las salidas en los puentes de comunicación (`bridge`).
+
+## Mejores Prácticas
+- Prefiere comandos de solo lectura siempre que sea posible.
+- Verifica siempre el código de salida (`exitCode`) y las salidas de error (`stderr`).
+- Usa rutas absolutas para mayor fiabilidad entre diferentes sistemas operativos.

package/packages/skills/src/bundled/system_notify/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: system_notify
+description: "Send system desktop notifications and interact via Canvas"
+version: 1.0.0
+author: Hive Team
+icon: "🔔"
+category: system
+permissions:
+  - desktop_notification
+  - canvas_write
+dependencies: []
+tools: [system_notify, notify, report_progress, canvas_render, canvas_ask, canvas_confirm, canvas_show_card, canvas_show_progress, canvas_show_list, canvas_clear]
+---
+
+# System Notify & Canvas Skill
+
+Esta skill permite al agente enviar notificaciones al sistema y renderizar componentes interactivos en el Canvas del usuario (UI).
+
+## Herramientas Disponibles
+
+### Notificaciones del Sistema
+- `notify`: Envía una notificación de escritorio tradicional.
+- `report_progress`: Informa sobre el progreso de tareas de larga duración.
+
+### Herramientas de Canvas (UI)
+- `canvas_render`: Renderiza componentes (botones, tablas, gráficos) en el Canvas.
+- `canvas_ask`: Muestra formularios dinámicos y espera la respuesta del usuario.
+- `canvas_confirm`: Muestra un diálogo de confirmación (Aceptar/Cancelar).
+- `canvas_show_card`: Muestra una tarjeta informativa con ítems etiquetados.
+- `canvas_show_progress`: Muestra barras de progreso múltiples para tareas complejas.
+- `canvas_show_list`: Muestra listas de clave-valor (útil para configuraciones).
+- `canvas_clear`: Limpia el contenido del Canvas para una sesión.
+
+## Uso Dinámico del Canvas
+
+El Canvas es ideal para presentar información estructurada que es difícil de leer en texto puro, o para requerir entradas complejas del usuario mediante formularios.
+
+### Ejemplo: Formulario de Registro
+```javascript
+canvas_ask({
+  title: "Datos de Usuario",
+  fields: [
+    { name: "email", label: "Correo Electrónico", type: "email", required: true },
+    { name: "role", label: "Rol", type: "select", options: [{label: "Admin", value: "admin"}] }
+  ]
+})
+```
+
+## Mejores Prácticas
+- **Concisión**: Mantén los mensajes de notificación cortos.
+- **Urgencia**: Usa niveles de urgencia (`low`, `normal`, `critical`) solo para eventos que realmente requieran atención inmediata.
+- **Limpieza**: Usa `canvas_clear` cuando cambies drásticamente de contexto para mantener el espacio de trabajo limpio.

package/packages/skills/src/bundled/voice/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: voice
+description: "Process audio transcriptions and synthesize speech"
+version: 1.0.0
+author: Hive Team
+icon: "🎙️"
+category: voice
+permissions:
+  - internet_access
+dependencies: []
+tools: [voice_transcribe, voice_speak]
+---
+
+# Voice Processing Skill
+
+Esta skill permite al agente interactuar mediante voz, transcribiendo audio a texto y convirtiendo texto a voz.
+
+## Herramientas Disponibles
+
+- `voice_transcribe`: Transcribe un archivo de audio a texto.
+- `voice_speak`: Convierte texto a audio y lo envía al canal de comunicación activo.
+
+## Mejores Prácticas
+- **Calidad de Audio**: Asegúrate de que los archivos de audio para transcripción sean legibles.
+- **Brevedad**: Para `voice_speak`, prefiere mensajes concisos para una mejor experiencia de usuario.

package/packages/skills/src/bundled/web_search/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: web_search
+description: "Search the internet for real-time information"
+version: 1.0.0
+author: Hive Team
+icon: "🔍"
+category: tools
+permissions:
+  - internet_access
+dependencies: []
+tools: [web_search]
+---
+
+# Web Search Skill
+
+Esta skill permite al agente buscar información actualizada en internet utilizando motores de búsqueda integrados.
+
+## Herramientas Disponibles
+
+- `web_search`: Realiza una búsqueda web y devuelve resultados con títulos, URLs y fragmentos de texto.
+
+## Parámetros
+
+- `query` (requerido): El término de búsqueda.
+- `numResults` (opcional): Número de resultados a devolver (por defecto: 5).
+
+## Mejores Prácticas
+- **Especificidad**: Usa términos de búsqueda precisos.
+- **Cruzar Datos**: Combina los resultados de búsqueda con la herramienta `web_fetch` (de la skill `http_client`) para obtener el contenido completo de una página si es necesario.

package/packages/skills/src/index.ts

@@ -0,0 +1 @@
+export * from "./loader.ts";

package/packages/skills/src/loader.ts

@@ -0,0 +1,282 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+
+export interface SkillsConfig {
+  allowBundled?: string[];
+  managedDir?: string;
+  extraDirs?: string[];
+  hotReload?: boolean;
+  maxSkillSizeKB?: number;
+}
+
+export interface Config {
+  skills?: SkillsConfig;
+  workspacePath?: string;
+}
+
+interface Logger {
+  debug: (msg: string, ...args: unknown[]) => void;
+  info: (msg: string, ...args: unknown[]) => void;
+  warn: (msg: string, ...args: unknown[]) => void;
+  error: (msg: string, ...args: unknown[]) => void;
+}
+
+function createLogger(): Logger {
+  return {
+    debug: (msg, ...args) => console.debug(`[skills] ${msg}`, ...args),
+    info: (msg, ...args) => console.info(`[skills] ${msg}`, ...args),
+    warn: (msg, ...args) => console.warn(`[skills] ${msg}`, ...args),
+    error: (msg, ...args) => console.error(`[skills] ${msg}`, ...args),
+  };
+}
+
+export interface SkillMetadata {
+  name: string;
+  version?: string;
+  author?: string;
+  description: string;
+  icon?: string;
+  category?: string;
+  permissions?: string[];
+  dependencies?: string[];
+  tools?: string[];
+  requirements?: {
+    os?: string[];
+    bins?: string[];
+    env?: string[];
+    config?: string[];
+  };
+  // Retrocompatibilidad con el campo metadata.hive previo
+  metadata?: {
+    hive?: {
+      emoji?: string;
+      bins?: string[];
+      userInvocable?: boolean;
+      requires?: {
+        config?: string[];
+        env?: string[];
+      };
+      install?: {
+        brew?: string;
+        apt?: string;
+        npm?: string;
+      };
+      os?: string[];
+    };
+  };
+}
+
+export interface Skill {
+  name: string;
+  description: string;
+  version?: string;
+  author?: string;
+  icon?: string;
+  category?: string;
+  content: string;
+  raw: string;
+  metadata: SkillMetadata;
+  source: "bundled" | "managed" | "workspace";
+  path: string;
+  permissions?: string[];
+  dependencies?: string[];
+  tools?: string[];
+}
+
+function parseFrontmatter(content: string): { frontmatter: Record<string, unknown>; body: string } {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+
+  try {
+    const frontmatter = yaml.load(match[1]!) as Record<string, unknown>;
+    const body = match[2]!;
+    return { frontmatter, body };
+  } catch {
+    return { frontmatter: {}, body: content };
+  }
+}
+
+export class SkillLoader {
+  private config: Config;
+  private log: Logger;
+  private cache: Map<string, Skill> = new Map();
+  private bundledDir: string;
+
+  constructor(config: Config) {
+    this.config = config;
+    this.log = createLogger();
+    this.bundledDir = path.join(__dirname, "bundled");
+  }
+
+  private expandPath(p: string): string {
+    if (p.startsWith("~")) {
+      return path.join(process.env.HOME ?? "", p.slice(1));
+    }
+    return p;
+  }
+
+  loadSkill(skillPath: string, source: Skill["source"]): Skill | null {
+    try {
+      const skillMdPath = path.join(skillPath, "SKILL.md");
+
+      if (!fs.existsSync(skillMdPath)) {
+        return null;
+      }
+
+      const content = fs.readFileSync(skillMdPath, "utf-8");
+      const { frontmatter, body } = parseFrontmatter(content);
+
+      const rawMetadata = (frontmatter.metadata as any) ?? {};
+      const hiveMetadata = rawMetadata.hive ?? {};
+
+      const name = (frontmatter.name as string) ?? path.basename(skillPath);
+      const description = (frontmatter.description as string) ?? "";
+      const version = (frontmatter.version as string) ?? "0.0.1";
+      const author = (frontmatter.author as string) ?? "Anonymous";
+      const icon = (frontmatter.icon as string) ?? hiveMetadata.emoji ?? "🧩";
+      const category = (frontmatter.category as string) ?? "general";
+
+      const permissions = (frontmatter.permissions as string[]) ?? [];
+      const dependencies = (frontmatter.dependencies as string[]) ?? [];
+      const tools = (frontmatter.tools as string[]) ?? [];
+
+      const metadata: SkillMetadata = {
+        ...(frontmatter as any),
+        name,
+        description,
+        version,
+        author,
+        icon,
+        category,
+        permissions,
+        dependencies,
+        tools
+      };
+
+      const skill: Skill = {
+        name,
+        description,
+        version,
+        author,
+        icon,
+        category,
+        content: body,
+        raw: content,
+        metadata,
+        source,
+        path: skillPath,
+        permissions,
+        dependencies,
+        tools
+      };
+
+      this.cache.set(name, skill);
+      return skill;
+    } catch (error) {
+      this.log.error(`Failed to load skill: ${skillPath}`, { error: (error as Error).message });
+      return null;
+    }
+  }
+
+  loadBundledSkills(): Skill[] {
+    const skills: Map<string, Skill> = new Map();
+
+    if (!fs.existsSync(this.bundledDir)) {
+      this.log.debug(`Bundled skills directory not found: ${this.bundledDir}`);
+      return [];
+    }
+
+    for (const entry of fs.readdirSync(this.bundledDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        const skill = this.loadSkill(path.join(this.bundledDir, entry.name), "bundled");
+        if (skill) {
+          skills.set(skill.name, skill);
+        }
+      }
+    }
+
+    this.log.debug(`Loaded ${skills.size} bundled skills`);
+    return Array.from(skills.values());
+  }
+
+  loadAllSkills(): Skill[] {
+    const skills: Map<string, Skill> = new Map();
+    const allowBundled = this.config.skills?.allowBundled;
+
+    // 1. Load bundled skills (lowest priority)
+    const bundledSkills = this.loadBundledSkills();
+    for (const skill of bundledSkills) {
+      // If allowBundled is undefined, empty, or contains the skill name, include it
+      if (!allowBundled || allowBundled.length === 0 || allowBundled.includes(skill.name)) {
+        skills.set(skill.name, skill);
+      }
+    }
+
+    // 2. Load managed skills (medium priority)
+    const managedDir = this.expandPath(this.config.skills?.managedDir ?? "~/.hive/skills");
+    if (fs.existsSync(managedDir)) {
+      for (const entry of fs.readdirSync(managedDir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          const skill = this.loadSkill(path.join(managedDir, entry.name), "managed");
+          if (skill) {
+            skills.set(skill.name, skill);
+          }
+        }
+      }
+    }
+
+    // 3. Load extra directories
+    const extraDirs = this.config.skills?.extraDirs ?? [];
+    for (const extraDir of extraDirs) {
+      const expandedDir = this.expandPath(extraDir);
+      if (fs.existsSync(expandedDir)) {
+        for (const entry of fs.readdirSync(expandedDir, { withFileTypes: true })) {
+          if (entry.isDirectory()) {
+            const skill = this.loadSkill(path.join(expandedDir, entry.name), "managed");
+            if (skill) {
+              skills.set(skill.name, skill);
+            }
+          }
+        }
+      }
+    }
+
+    // 4. Load workspace skills (highest priority)
+    const workspacePath = this.config.workspacePath ?? process.cwd();
+    const workspaceSkillsDir = path.join(workspacePath, "skills");
+    if (fs.existsSync(workspaceSkillsDir)) {
+      for (const entry of fs.readdirSync(workspaceSkillsDir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          const skill = this.loadSkill(path.join(workspaceSkillsDir, entry.name), "workspace");
+          if (skill) {
+            skills.set(skill.name, skill);
+          }
+        }
+      }
+    }
+
+    this.log.info(`Loaded ${skills.size} total skills`);
+    return Array.from(skills.values());
+  }
+
+  getSkill(name: string): Skill | undefined {
+    return this.cache.get(name);
+  }
+
+  listSkills(): string[] {
+    return Array.from(this.cache.keys());
+  }
+
+  clearCache(): void {
+    this.cache.clear();
+  }
+}
+
+export function createSkillLoader(config: Config): SkillLoader {
+  return new SkillLoader(config);
+}
+

package/packages/tools/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@johpaz/hive-tools",
+  "version": "1.1.0",
+  "private": true,
+  "description": "Native tools for Hive AI Gateway - Browser, Cron, FileSystem, Canvas",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johpaz/hive.git",
+    "directory": "packages/tools"
+  },
+  "keywords": [
+    "hive",
+    "ai",
+    "tools",
+    "browser",
+    "cron",
+    "filesystem",
+    "canvas"
+  ],
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@johpaz/hive-core": "^1.1.0",
+    "cron-parser": "^5.5.0",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "typescript": "latest",
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./browser": "./src/browser/index.ts",
+    "./cron": "./src/cron/index.ts",
+    "./filesystem": "./src/filesystem/index.ts",
+    "./canvas": "./src/canvas/index.ts"
+  }
+}

package/packages/tools/src/browser/browser.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  createBrowserNavigateTool,
+  createBrowserFetchTool,
+  createBrowserScreenshotTool,
+  createBrowserClickTool,
+  createBrowserTypeTool,
+  createBrowserTools,
+} from "./index";
+
+describe("Browser Tools", () => {
+  describe("createBrowserNavigateTool", () => {
+    it("creates tool with correct name and description", () => {
+      const tool = createBrowserNavigateTool();
+      expect(tool.name).toBe("browser_navigate");
+      expect(tool.description).toContain("Navigate");
+    });
+
+    it("has required parameters", () => {
+      const tool = createBrowserNavigateTool();
+      expect(tool.parameters.type).toBe("object");
+      expect(tool.parameters.required).toContain("url");
+    });
+
+    it("fetches content from a URL", async () => {
+      const tool = createBrowserNavigateTool();
+      try {
+        const result = await tool.execute({
+          url: "https://example.com",
+        }) as { success: boolean; content: string };
+
+        expect(result.success).toBe(true);
+        expect(result.content).toBeDefined();
+      } catch (error) {
+        console.log("Skipping URL fetch test due to network/cert issues");
+      }
+    }, 30000);
+  });
+
+  describe("createBrowserFetchTool", () => {
+    it("creates tool with correct name", () => {
+      const tool = createBrowserFetchTool();
+      expect(tool.name).toBe("browser_fetch");
+    });
+
+    it("fetches JSON from API", async () => {
+      const tool = createBrowserFetchTool();
+      try {
+        const result = await tool.execute({
+          url: "https://jsonplaceholder.typicode.com/posts/1",
+        }) as { success: boolean; data: unknown };
+
+        expect(result.success).toBe(true);
+        expect(result.data).toBeDefined();
+      } catch (error) {
+        console.log("Skipping URL fetch test due to network/cert issues");
+      }
+    }, 30000);
+  });
+
+  describe("createBrowserScreenshotTool", () => {
+    it("creates tool with placeholder response", async () => {
+      const tool = createBrowserScreenshotTool();
+      const result = await tool.execute({
+        url: "https://example.com",
+      }) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("puppeteer");
+    });
+  });
+
+  describe("createBrowserClickTool", () => {
+    it("creates tool with placeholder response", async () => {
+      const tool = createBrowserClickTool();
+      const result = await tool.execute({
+        selector: "#button",
+      }) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("puppeteer");
+    });
+  });
+
+  describe("createBrowserTypeTool", () => {
+    it("creates tool with placeholder response", async () => {
+      const tool = createBrowserTypeTool();
+      const result = await tool.execute({
+        selector: "#input",
+        text: "hello",
+      }) as { success: boolean; error: string };
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("puppeteer");
+    });
+  });
+
+  describe("createBrowserTools", () => {
+    it("returns all browser tools", () => {
+      const tools = createBrowserTools();
+      expect(tools.length).toBe(5);
+      expect(tools.map((t) => t.name)).toEqual([
+        "browser_navigate",
+        "browser_fetch",
+        "browser_screenshot",
+        "browser_click",
+        "browser_type",
+      ]);
+    });
+  });
+});