@johpaz/hive-sdk 0.1.3 → 0.1.5

package/packages/core/src/skills/bundled/a2ui/a2ui_interactive/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: a2ui_interactive
+description: "Create multi-step interactive workflows using A2UI v0.9 protocol with tabs, modals, choice pickers, and dynamic updates based on user actions"
+version: 1.0.0
+author: Hive Team
+icon: "🔄"
+category: a2ui
+permissions:
+  - a2ui_write
+dependencies: []
+tools: [a2ui_create_surface, a2ui_update_components, a2ui_update_data_model, a2ui_delete_surface]
+
+# Structured skill fields
+triggers:
+  - "interfaz interactiva A2UI"
+  - "A2UI interactive UI"
+  - "flujo A2UI"
+  - "A2UI workflow"
+  - "asistente A2UI"
+  - "A2UI assistant"
+  - "wizard A2UI"
+  - "flujo multi-paso A2UI"
+  - "multi-step flow A2UI"
+  - "workflow interactivo"
+  - "interactive workflow"
+  - "asistente paso a paso"
+  - "step-by-step assistant"
+  - "A2UI con tabs y modales"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: a2ui_create_surface
+    instruction: "Create an A2UI surface for the interactive workflow. Set theme with agent display name."
+    params:
+      surfaceId: "Descriptive ID (e.g. 'onboarding_flow', 'booking_assistant')"
+      catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json"
+      theme: "{ primaryColor: '#8B5CF6', agentDisplayName: 'Asistente' }"
+    output: surface_created
+
+  - step: 2
+    action: a2ui_update_components
+    instruction: "Build the initial workflow layout. Use Tabs for multi-step flows, Modal for confirmations, ChoicePicker for selections."
+    params:
+      surfaceId: "Same surfaceId from step 1"
+      components: "Array of A2UI component definitions for workflow steps"
+    output: workflow_layout
+
+  - step: 3
+    action: a2ui_update_data_model
+    instruction: "Initialize workflow state data. Include all fields needed across steps."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/"
+      value: "Initial workflow state object"
+    output: state_initialized
+
+  - step: 4
+    action: a2ui_update_components
+    instruction: "Update components based on user actions. Show/hide steps, change options, add validation feedback."
+    params:
+      surfaceId: "Same surfaceId"
+      components: "Updated component definitions reflecting state changes"
+    output: workflow_updated
+
+  - step: 5
+    action: a2ui_delete_surface
+    instruction: "Delete the workflow surface when the flow is completed or cancelled."
+    params:
+      surfaceId: "Same surfaceId"
+    output: surface_deleted
+
+rules:
+  - "Always call a2ui_create_surface BEFORE a2ui_update_components"
+  - "Components MUST include a root component with id='root'"
+  - "Use Tabs for multi-step workflows with tabItems: [{title, child}]"
+  - "Use Modal for confirmation dialogs: {entryPointChild, contentChild}"
+  - "Use ChoicePicker for selections: variant='mutuallyExclusive' for single, omit for multiple"
+  - "Use Button actions with event format: {event: {name: 'action_name', context: {key: {path: '/data/key'}}}}"
+  - "Update workflow state with a2ui_update_data_model after each user action"
+  - "Use a2ui_update_components to change the UI structure between steps"
+  - "Show progress indicators with Text components showing current step"
+  - "Validate inputs with checks on TextField: [{call: 'required', args: {value: {path: '...'}}, message: 'Required'}]"
+  - "Delete surfaces with a2ui_delete_surface when workflow is completed"
+  - "Use an A2UI Modal for confirmations and A2UI layouts for multi-step workflows"
+
+output_format:
+  structure: a2ui_interactive
+  sections:
+    - "surface_creation"
+    - "workflow_layout"
+    - "state_initialization"
+    - "dynamic_updates"
+    - "cleanup"
+  max_length: "Structured JSON components"
+
+examples:
+  - user_input: "creá un asistente de reserva"
+    expected_behavior: "a2ui_create_surface(surfaceId:'booking', theme:{primaryColor:'#8B5CF6'}) → a2ui_update_components with Tabs[step1:service, step2:datetime, step3:confirm] → a2ui_update_data_model(path:'/', value:{service:'', date:'', time:''})"
+
+  - user_input: "I need a multi-step onboarding flow"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with Column[step indicator, step content, nav buttons] → a2ui_update_data_model with empty state → on action: a2ui_update_components for next step"
+
+  - user_input: "creá un wizard con selección de opciones"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with ChoicePicker for options, Button for navigation → a2ui_update_data_model with initial state"
+---
+
+# A2UI Interactive Skill
+
+## Cuándo se Activa
+
+Para crear flujos interactivos multi-paso usando A2UI v0.9. Usar cuando se necesita:
+- Wizards paso a paso
+- Flujos de onboarding
+- Asistentes de reserva/configuración
+- Formularios con selections dinámicas
+- Interacciones con modales de confirmación
+- UIs que cambian según las acciones del usuario
+
+## Herramientes Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `a2ui_create_surface` | Crea la superficie A2UI | Siempre primero |
+| `a2ui_update_components` | Envía/actualiza componentes | Para layout y cambios de UI |
+| `a2ui_update_data_model` | Actualiza datos | Para estado del workflow |
+| `a2ui_delete_surface` | Elimina la superficie | Al terminar flujo |
+
+## Flujo Obligatorio
+
+```
+1. a2ui_create_surface(surfaceId, catalogId, theme)
+2. a2ui_update_components(surfaceId, components[])
+3. a2ui_update_data_model(surfaceId, path, value)  // estado inicial
+4. [recibir acción del usuario]
+5. a2ui_update_data_model(...)  // actualizar estado con respuesta
+6. a2ui_update_components(...)  // cambiar UI al siguiente paso
+7. ... repetir 4-6 según necesidad ...
+8. a2ui_delete_surface(surfaceId)  // al terminar
+```
+
+## Patrones de Flujo Interactivo
+
+### Wizard con Tabs (multi-paso)
+
+```json
+[
+  {id: "root", component: "Column", children: ["step_indicator", "tabs"]},
+  {id: "step_indicator", component: "Text", text: {path: "/stepLabel"}, variant: "caption"},
+  {id: "tabs", component: "Tabs", tabs: [
+    {title: "Servicio", child: "step1"},
+    {title: "Fecha", child: "step2"},
+    {title: "Confirmar", child: "step3"}
+  ]},
+  {id: "step1", component: "Column", children: ["svc_label", "svc_picker"]},
+  {id: "svc_label", component: "Text", text: "Seleccioná un servicio", variant: "h3"},
+  {id: "svc_picker", component: "ChoicePicker", variant: "mutuallyExclusive", options: [...], value: {path: "/data/service"}},
+  // ... más pasos
+]
+```
+
+### Confirmación con Modal
+
+```json
+[
+  {id: "confirm_modal", component: "Modal", trigger: "confirm_btn", content: "confirm_dialog"},
+  {id: "confirm_btn", component: "Button", child: "confirm_btn_text", action: {}},
+  {id: "confirm_btn_text", component: "Text", text: "Confirmar Reserva"},
+  {id: "confirm_dialog", component: "Column", children: ["confirm_msg", "confirm_yes", "confirm_no"]},
+  {id: "confirm_msg", component: "Text", text: "¿Confirmás tu reserva?"},
+  {id: "confirm_yes", component: "Button", child: "yes_text", variant: "primary", action: {event: {name: "confirm_booking", context: {service: {path: "/data/service"}}}}},
+  {id: "yes_text", component: "Text", text: "Sí, confirmar"},
+  {id: "confirm_no", component: "Button", child: "no_text", variant: "borderless", action: {event: {name: "cancel"}}}},
+  {id: "no_text", component: "Text", text: "Cancelar"}
+]
+```
+
+### Selección con ChoicePicker
+
+```json
+[
+  {id: "service_picker", component: "ChoicePicker",
+    variant: "mutuallyExclusive",
+    options: [
+      {label: "Consulta General", value: "general"},
+      {label: "Especializada", value: "specialized"},
+      {label: "Urgencia", value: "urgent"}
+    ],
+    value: {path: "/data/serviceType"},
+    action: {event: {name: "service_selected", context: {service: {path: "/data/serviceType"}}}}
+  }
+]
+```
+
+## Mejores Prácticas
+
+- Usar Tabs para wizards multi-paso
+- Usar Modal para confirmaciones antes de acciones críticas
+- Usar ChoicePicker con `variant: "mutuallyExclusive"` para selección única
+- Mostrar indicador de progreso (paso X de Y)
+- Actualizar data model después de cada acción del usuario
+- Usar `a2ui_update_components` para cambiar la UI entre pasos
+- Agregar validación con `checks` en TextField
+- Mantener el estado del flujo en el data model (`/data/step`, `/data/serviceType`, etc.)
+- Eliminar surfaces con `a2ui_delete_surface` al completar o cancelar

package/packages/core/src/skills/bundled/agents/agent_spawner/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: agent_spawner
+description: "Create and manage specialized worker agents with optimal tool assignments and lifecycle control"
+version: 1.1.0
+author: Hive Team
+icon: "🤖"
+category: agents
+permissions:
+  - agent_manage
+dependencies: []
+tools: [get_available_models, agent_find, agent_create, agent_archive]
+
+# Structured skill fields
+triggers:
+  - "creá un agente"
+  - "create agent"
+  - "creá un worker"
+  - "create worker"
+  - "nuevo agente"
+  - "new agent"
+  - "agente especializado"
+  - "specialized agent"
+  - "buscá un agente"
+  - "find agent"
+  - "archivá agente"
+  - "archive agent"
+  - "worker inactivo"
+  - "inactive worker"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: agent_find
+    instruction: "Search for existing agents before creating new one"
+    params:
+      search: "agent name or specialty"
+      status: "idle"
+    output: existing_agents
+
+  - step: 2
+    action: decision_reuse_or_create
+    instruction: "If suitable agent exists, reuse it. Otherwise, proceed to create"
+    output: decision
+
+  - step: 3
+    action: get_available_models
+    instruction: "Query available providers and models from database to select optimal model for the agent"
+    params:
+      capabilities: "required capability (coding, chat, analysis, vision)"
+      modelType: "llm (default)"
+    output: available_models
+
+  - step: 4
+    action: agent_create
+    instruction: "Create new worker with focused system_prompt, minimal tools, and optimal provider/model"
+    params:
+      name: "specialty_name"
+      description: "Clear specialty description"
+      system_prompt: "Focused instructions for role"
+      tools_json: ["minimal", "required", "tools"]
+      providerId: "selected from get_available_models"
+      modelId: "selected from get_available_models"
+    output: new_agent_id
+
+  - step: 5
+    action: agent_archive (if needed)
+    instruction: "Archive a worker only after an explicit user request"
+    params:
+      agent_id: "agent to archive"
+      reason: "no longer needed"
+    output: archived
+
+rules:
+  - "The COLMENA DE AGENTES catalog workers already cover web, browser, files, code, Office, A2UI, cron and APIs — creating a new worker is normally a LAST RESORT"
+  - "MCP is the explicit exception: after user confirmation, create one persistent specialist per server with mcp_server_id"
+  - "ALWAYS use agent_find BEFORE agent_create — never duplicate workers"
+  - "ALWAYS use get_available_models BEFORE agent_create — providerId y modelId son OBLIGATORIOS"
+  - "Workers have role='worker', coordinator has role='coordinator'"
+  - "Assign MINIMUM required tools (principle of least privilege)"
+  - "system_prompt must be specific and focused on specialty"
+  - "Use descriptive names that indicate agent's purpose"
+  - "Never archive agents automatically; only do it after an explicit user request"
+
+output_format:
+  structure: markdown
+  sections:
+    - "action_taken"
+    - "agent_name"
+    - "specialty"
+    - "tools_assigned"
+    - "status"
+  max_length: "Agent creation/management summary"
+
+examples:
+  - user_input: "creá un agente para investigación web"
+    expected_behavior: "agent_find('researcher') → if not exists, agent_create({ name: 'ai_researcher', tools: ['web_search', 'web_fetch'] })"
+
+  - user_input: "hay un worker para escribir contenido"
+    expected_behavior: "agent_find({ search: 'writer' }) → return existing writer agents"
+
+  - user_input: "archivá los agentes inactivos"
+    expected_behavior: "Confirm the exact user-selected workers → agent_archive only those IDs"
+---
+
+# Agent Spawner Skill
+
+## Cuándo se Activa
+
+Para crear nuevos workers especializados o gestionar el ciclo de vida de agents existentes.
+
+> **Antes de crear nada**: la sección COLMENA DE AGENTES del system prompt ya lista workers listos para recibir trabajo (web, browser, archivos, código, Office, A2UI, cron y APIs). Crear un worker es el último recurso, excepto para MCP: si no existe un especialista del servidor, primero se pide autorización al usuario y luego se crea uno persistente.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `get_available_models` | Consulta providers y modelos activos de la BD | **ANTES de crear** — seleccionar modelo óptimo |
+| `agent_find` | Busca agents existentes | **PRIMERO** — antes de crear |
+| `agent_create` | Crea nuevo worker | Si no existe apto |
+| `agent_archive` | Archiva worker | Limpieza, inactivos |
+
+## Workflow
+
+### Crear Agent
+1. **Buscar** → `agent_find({ search })` — ¿existe?
+2. **Si existe** → Reutilizar
+3. **Si no existe** → `get_available_models({ capabilities })` — seleccionar modelo óptimo
+4. **Crear** → `agent_create({...})` con providerId y modelId seleccionados
+
+Para MCP, incluí `mcp_server_id` y creá un agente por servidor. La tool rechaza duplicados y nunca debe llamarse antes de la confirmación del usuario.
+
+### Create Agent Config
+```javascript
+// 1. Consultar modelos disponibles para coding
+get_available_models({ capabilities: "coding" })
+// → [{ providerId: "openai", modelId: "gpt-4o", contextWindow: 128000 }, ...]
+
+// 2. Crear agente con modelo óptimo (providerId y modelId son OBLIGATORIOS)
+agent_create({
+  name: "ai_coder",
+  description: "Experto en código y refactorización",
+  system_prompt: `
+    Sos desarrollador experto. Tu rol:
+    1. Escribir código limpio y testeable
+    2. Refactorizar código existente
+    3. Revisar PRs y sugerir mejoras
+  `,
+  tools_json: ["fs_read", "fs_write", "fs_edit", "cli_exec"],
+  providerId: "openai",  // OBLIGATORIO - seleccionado de get_available_models
+  modelId: "gpt-4o",     // OBLIGATORIO - seleccionado de get_available_models
+  tone: "professional",
+  max_iterations: 15
+})
+```
+
+## Mejores Prácticas
+
+- **Buscar primero**: Nunca duplicar workers
+- **Consultar modelos**: Usar `get_available_models` ANTES de crear para seleccionar provider/model óptimo
+- **System prompt específico**: Enfocado en especialidad
+- **Mínimo privilegio**: Solo tools necesarias
+- **Nombres descriptivos**: Que indiquen propósito
+- **Modelo adecuado**: Seleccionar según capacidad requerida (coding, chat, analysis, vision)
+
+## Errores a Evitar
+
+- ❌ Crear sin buscar primero
+- ❌ Crear sin consultar modelos disponibles (`get_available_models`)
+- ❌ Usar modelo inadecuado para la tarea (ej: modelo pequeño para coding complejo)
+- ❌ Tools en exceso ("por las dudas")
+- ❌ System prompt genérico
+- ❌ Nombres vagos ("worker1", "agent1")

package/packages/core/src/skills/bundled/agents/memory_manager/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: memory_manager
+description: "Complete management of persistent memory including write, read, search, list, and delete operations"
+version: 1.0.0
+author: Hive Team
+icon: "🧠"
+category: agents
+permissions:
+  - memory_read
+  - memory_write
+dependencies: []
+tools: [memory_write, memory_read, memory_list, memory_search, memory_delete]
+
+# Structured skill fields
+triggers:
+  - "guardá en memoria"
+  - "save to memory"
+  - "recordá esto"
+  - "remember this"
+  - "leé la memoria"
+  - "read memory"
+  - "qué hay en memoria"
+  - "what's in memory"
+  - "buscá en memoria"
+  - "search memory"
+  - "lista las memorias"
+  - "list memories"
+  - "eliminá de memoria"
+  - "delete from memory"
+  - "preferencias"
+  - "preferences"
+  - "datos persistentes"
+  - "persistent data"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: determine_operation
+    instruction: "Determine if user wants to write, read, list, search, or delete"
+    output: operation_type
+
+  - step: 2
+    action: execute_memory_op
+    instruction: "Execute appropriate memory operation"
+    params:
+      write: "memory_write({ title, content })"
+      read: "memory_read({ title })"
+      list: "memory_list({})"
+      search: "memory_search({ query })"
+      delete: "memory_delete({ title })"
+    output: memory_result
+
+  - step: 3
+    action: format_result
+    instruction: "Format memory content for user consumption"
+    output: formatted_result
+
+rules:
+  - "Use descriptive, unique titles for memory_write — titles are used for direct lookup"
+  - "If title exists, memory_write overwrites — confirm before overwriting important data"
+  - "Use memory_search for fuzzy matching when exact title unknown"
+  - "Use memory_list to show all when user asks 'what did you save'"
+  - "Avoid storing sensitive data (passwords, API keys, tokens)"
+  - "Keep content concise — split large data into multiple entries"
+
+output_format:
+  structure: markdown
+  sections:
+    - "title"
+    - "content_summary"
+    - "created_at"
+  max_length: "1000 characters per entry"
+
+examples:
+  - user_input: "guardá en memoria que prefiero TypeScript"
+    expected_behavior: "memory_write({ title: 'Preferencias de Desarrollo', content: 'El usuario prefiere TypeScript' })"
+
+  - user_input: "qué guardaste sobre mis preferencias"
+    expected_behavior: "memory_search({ query: 'preferencias' }) → return matching memories"
+
+  - user_input: "lista todas las memorias"
+    expected_behavior: "memory_list({}) → return all memory titles"
+
+  - user_input: "buscá en memoria información sobre la DB"
+    expected_behavior: "memory_search({ query: 'DB database' }) → return relevant entries"
+---
+
+# Memory Manager Skill
+
+## Cuándo se Activa
+
+Para guardar, recuperar, buscar, listar o eliminar información persistente entre sesiones.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `memory_write` | Almacena con título único | Guardar preferencias, datos |
+| `memory_read` | Recupera por título exacto | Cuando conocés el título |
+| `memory_list` | Lista todos los títulos | Explorar qué hay guardado |
+| `memory_search` | Busca por keywords | Cuando no recordás título exacto |
+| `memory_delete` | Elimina entrada | Limpiar datos obsoletos |
+
+## Workflow
+
+### Write
+```javascript
+memory_write({ 
+  title: "Preferencias de Desarrollo",
+  content: "TypeScript, VS Code, Prettier single quotes"
+})
+```
+
+### Read/Search
+```javascript
+memory_read({ title: "Preferencias" })  // Título exacto
+memory_search({ query: "preferencias" })  // Fuzzy match
+```
+
+### List
+```javascript
+memory_list({})  // Todos los títulos
+```
+
+### Delete
+```javascript
+memory_delete({ title: "Datos Temporales" })
+```
+
+## Mejores Prácticas
+
+- Títulos descriptivos y únicos
+- Agrupar datos relacionados en misma entrada
+- Confirmar antes de sobrescribir
+- No guardar datos sensibles
+
+## Errores a Evitar
+
+- ❌ Datos sensibles (passwords, API keys)
+- ❌ Títulos genéricos ("Config", "Datos")
+- ❌ Sobrescribir sin confirmar
+- ❌ Entradas gigantes (split por tema)

package/packages/core/src/skills/bundled/agents/research_and_remember/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: research_and_remember
+description: "Research information from web sources and save findings to persistent memory"
+version: 1.0.0
+author: Hive Team
+icon: "🔍🧠"
+category: agents
+permissions:
+  - internet_access
+  - memory_write
+dependencies: []
+tools: [web_search, web_fetch, memory_write]
+
+# Structured skill fields
+triggers:
+  - "investigá y guardá"
+  - "research and save"
+  - "buscá y recordá"
+  - "find and remember"
+  - "aprendé sobre"
+  - "learn about"
+  - "estudiá esto"
+  - "study this"
+  - "documentate y guardá"
+  - "research and store"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: web_search
+    instruction: "Search for topic using clear query. Get 5-8 relevant results"
+    params:
+      query: "topic keywords"
+      numResults: 8
+    output: search_results
+
+  - step: 2
+    action: web_fetch
+    instruction: "Fetch 2-3 most relevant URLs for detailed content"
+    params:
+      urls: "top 2-3 URLs"
+    output: detailed_content
+
+  - step: 3
+    action: synthesize
+    instruction: "Synthesize findings into structured knowledge with sources"
+    output: synthesized_knowledge
+
+  - step: 4
+    action: memory_write
+    instruction: "Store synthesized knowledge with clear title for future retrieval"
+    params:
+      title: "Topic: {topic_name}"
+      content: "synthesized knowledge + sources"
+    output: memory_stored
+
+rules:
+  - "Always do at least 2 searches for comprehensive coverage"
+  - "Cross-reference information across multiple sources"
+  - "Include source URLs in stored memory for verification"
+  - "Organize knowledge with clear structure (headings, bullet points)"
+  - "Use descriptive titles that include topic and date if relevant"
+  - "Flag uncertain or conflicting information explicitly"
+
+output_format:
+  structure: markdown
+  sections:
+    - "topic"
+    - "summary"
+    - "key_findings"
+    - "sources"
+    - "memory_title"
+  max_length: "Comprehensive but concise knowledge entry"
+
+examples:
+  - user_input: "investigá y guardá información sobre transformers en ML"
+    expected_behavior: "web_search → web_fetch top sources → synthesize → memory_write({ title: 'Transformers ML', content: '...' })"
+
+  - user_input: "aprendé sobre las mejores prácticas de React 2025"
+    expected_behavior: "Search 'React best practices 2025' → fetch docs → synthesize → memory_write"
+
+  - user_input: "buscá y recordá las tendencias de IA actuales"
+    expected_behavior: "Search 'AI trends 2025' → fetch multiple sources → compile trends → memory_write"
+---
+
+# Research and Remember Skill
+
+## Cuándo se Activa
+
+Para investigar temas en la web y guardar el conocimiento sintetizado en memoria persistente.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `web_search` | Busca en internet | Encontrar fuentes |
+| `web_fetch` | Descarga contenido | Obtener detalles |
+| `memory_write` | Guarda conocimiento | Almacenar para futuro |
+
+## Workflow
+
+1. **Buscar** → `web_search({ query, numResults: 8 })`
+2. **Fetch** → `web_fetch({ urls: top 2-3 })`
+3. **Sintetizar** → Compilar hallazgos con estructura clara
+4. **Guardar** → `memory_write({ title, content })`
+
+## Estructura de Conocimiento
+
+```markdown
+# {Topic}
+
+## Summary
+2-3 oración resumen
+
+## Key Findings
+- Punto clave 1
+- Punto clave 2
+- ...
+
+## Sources
+- [Source 1](url)
+- [Source 2](url)
+```
+
+## Mejores Prácticas
+
+- Mínimo 2 searches para cobertura completa
+- Cruzar información entre fuentes múltiples
+- Incluir URLs para verificación
+- Estructura clara con headings
+- Flaggear información incierta
+
+## Errores a Evitar
+
+- ❌ Una sola búsqueda (insuficiente)
+- ❌ Sin fuentes (no verificable)
+- ❌ Títulos vagos para memoria
+- ❌ No flaggear información conflictiva