zugzbot 1.0.6 → 1.0.7

package/.utils/docs_opencode/tools.md

@@ -0,0 +1,364 @@
+# Herramientas
+
+Administre las herramientas que puede usar un LLM.
+
+Las herramientas permiten que LLM realice acciones en su código base. OpenCode viene con un conjunto de herramientas integradas, pero puede ampliarlo con [herramientas personalizadas](https://opencode.ai/docs/custom-tools) o [servidores MCP](https://opencode.ai/docs/mcp-servers).
+
+De forma predeterminada, todas las herramientas están **habilitadas** y no necesitan permiso para ejecutarse. Puede controlar el comportamiento de la herramienta a través de [permisos](https://opencode.ai/docs/permissions).
+
+---
+
+## [Configuración](#configuración)
+
+Utilice el campo `permission` para controlar el comportamiento de la herramienta. Puede permitir, denegar o exigir aprobación para cada herramienta.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny",
+    "bash": "ask",
+    "webfetch": "allow"
+  }
+}
+```
+
+También puedes utilizar comodines para controlar varias herramientas a la vez. Por ejemplo, para solicitar aprobación para todas las herramientas de un servidor MCP:
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "mymcp_*": "ask"
+  }
+}
+```
+
+[Más información](https://opencode.ai/docs/permissions) sobre la configuración de permisos.
+
+---
+
+## [Integradas](#integradas)
+
+Aquí están todas las herramientas integradas disponibles en OpenCode.
+
+---
+
+### [bash](#bash)
+
+Ejecute comandos de shell en el entorno de su proyecto.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": "allow"
+  }
+}
+```
+
+Esta herramienta permite que LLM ejecute comandos de terminal como `npm install`, `git status` o cualquier otro comando de shell.
+
+---
+
+### [edit](#edit)
+
+Modifique archivos existentes utilizando reemplazos de cadenas exactas.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "allow"
+  }
+}
+```
+
+Esta herramienta realiza ediciones precisas de archivos reemplazando coincidencias de texto exactas. Es la forma principal en que LLM modifica el código.
+
+---
+
+### [write](#write)
+
+Cree nuevos archivos o sobrescriba los existentes.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "allow"
+  }
+}
+```
+
+Utilice esto para permitir que LLM cree nuevos archivos. Sobrescribirá los archivos existentes si ya existen.
+
+> [!NOTE]
+> La herramienta `write` está controlada por el permiso `edit`, que cubre todas las modificaciones de archivos (`edit`, `write`, `patch`).
+
+---
+
+### [read](#read)
+
+Lea el contenido del archivo desde su base de código.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "read": "allow"
+  }
+}
+```
+
+Esta herramienta lee archivos y devuelve su contenido. Admite la lectura de rangos de líneas específicos para archivos grandes.
+
+---
+
+### [grep](#grep)
+
+Busque contenidos de archivos utilizando expresiones regulares.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "grep": "allow"
+  }
+}
+```
+
+Búsqueda rápida de contenido en su base de código. Admite sintaxis de expresiones regulares completa y filtrado de patrones de archivos.
+
+---
+
+### [glob](#glob)
+
+Encuentre archivos por coincidencia de patrones.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "glob": "allow"
+  }
+}
+```
+
+Busque archivos usando patrones globales como `**/*.js` o `src/**/*.ts`. Devuelve rutas de archivos coincidentes ordenadas por hora de modificación.
+
+---
+
+### [lsp (experimental)](#lsp-experimental)
+
+Interactúe con sus servidores LSP configurados para obtener funciones de inteligencia de código como definiciones, referencias, información de desplazamiento y jerarquía de llamadas.
+
+> [!NOTE]
+> Esta herramienta solo está disponible cuando `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` (o `OPENCODE_EXPERIMENTAL=true`).
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "lsp": "allow"
+  }
+}
+```
+
+Las operaciones admitidas incluyen `goToDefinition`, `findReferences`, `hover`, `documentSymbol`, `workspaceSymbol`, `goToImplementation`, `prepareCallHierarchy`, `incomingCalls` y `outgoingCalls`.
+
+Para configurar qué servidores LSP están disponibles para su proyecto, consulte [Servidores LSP](https://opencode.ai/docs/lsp).
+
+---
+
+### [patch](#patch)
+
+Aplicar parches a los archivos.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "allow"
+  }
+}
+```
+
+Esta herramienta aplica archivos de parche a su código base. Útil para aplicar diferencias y parches de diversas fuentes.
+
+> [!NOTE]
+> La herramienta `patch` está controlada por el permiso `edit`, que cubre todas las modificaciones de archivos (`edit`, `write`, `patch`).
+
+---
+
+### [skill](#skill)
+
+Cargue una [habilidad](https://opencode.ai/docs/skills) (un archivo `SKILL.md`) y devuelva su contenido en la conversación.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "skill": "allow"
+  }
+}
+```
+
+---
+
+### [todowrite](#todowrite)
+
+Administre listas de tareas pendientes durante las sesiones de codificación.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "todowrite": "allow"
+  }
+}
+```
+
+Crea y actualiza listas de tareas para realizar un seguimiento del progreso durante operaciones complejas. El LLM usa esto para organizar tareas de varios pasos.
+
+> [!NOTE]
+> Esta herramienta está deshabilitada para los subagentes de forma predeterminada, pero puede habilitarla manualmente. [Más información](https://opencode.ai/docs/agents/#permissions)
+
+---
+
+### [webfetch](#webfetch)
+
+Obtener contenido web.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "webfetch": "allow"
+  }
+}
+```
+
+Permite que LLM busque y lea páginas web. Útil para buscar documentación o investigar recursos en línea.
+
+---
+
+### [websearch](#websearch)
+
+Busque información en la web.
+
+> [!NOTE]
+> Esta herramienta solo está disponible cuando se utiliza el proveedor OpenCode o cuando la variable de entorno `OPENCODE_ENABLE_EXA` está configurada en cualquier valor verdadero (por ejemplo, `true` o `1`).
+> Para habilitar al iniciar OpenCode:
+> **File**: Ventana de terminal
+> ```bash
+> OPENCODE_ENABLE_EXA=1 opencode
+> ```
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "websearch": "allow"
+  }
+}
+```
+
+Realiza búsquedas web utilizando Exa AI para encontrar información relevante en línea. Útil para investigar temas, encontrar eventos actuales o recopilar información más allá del límite de datos de entrenamiento.
+
+No se requiere ninguna clave API: la herramienta se conecta directamente al servicio MCP alojado de Exa AI sin autenticación.
+
+> [!TIP]
+> Utilice `websearch` cuando necesite encontrar información (descubrimiento) y `webfetch` cuando necesite recuperar contenido de una URL específica (recuperación).
+
+---
+
+### [question](#question)
+
+Haga preguntas al usuario durante la ejecución.
+
+**File**: opencode.json
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "question": "allow"
+  }
+}
+```
+
+Esta herramienta permite que LLM haga preguntas al usuario durante una tarea. Es útil para:
+
+- Recopilar preferencias o requisitos del usuario.
+- Aclarar instrucciones ambiguas
+- Tomar decisiones sobre las opciones de implementación.
+- Ofrecer opciones sobre qué dirección tomar.
+
+Cada pregunta incluye un encabezado, el texto de la pregunta y una lista de opciones. Los usuarios pueden seleccionar entre las opciones proporcionadas o escribir una respuesta personalizada. Cuando hay varias preguntas, los usuarios pueden navegar entre ellas antes de enviar todas las respuestas.
+
+---
+
+## [Herramientas personalizadas](#herramientas-personalizadas)
+
+Las herramientas personalizadas le permiten definir sus propias funciones a las que LLM puede llamar. Estos están definidos en su archivo de configuración y pueden ejecutar código arbitrario.
+
+[Más información](https://opencode.ai/docs/custom-tools) sobre la creación de herramientas personalizadas.
+
+---
+
+## [Servidores MCP](#servidores-mcp)
+
+Los servidores MCP (Model Context Protocol) le permiten integrar herramientas y servicios externos. Esto incluye acceso a bases de datos, integraciones API y servicios de terceros.
+
+[Más información](https://opencode.ai/docs/mcp-servers) sobre la configuración de servidores MCP.
+
+---
+
+## [Internos](#internos)
+
+Internamente, herramientas como `grep` y `glob` usan [ripgrep](https://github.com/BurntSushi/ripgrep) bajo el capó. De forma predeterminada, ripgrep respeta los patrones `.gitignore`, lo que significa que los archivos y directorios enumerados en su `.gitignore` se excluirán de las búsquedas y listados.
+
+---
+
+### [Ignorar patrones](#ignorar-patrones)
+
+Para incluir archivos que normalmente se ignorarían, cree un archivo `.ignore` en la raíz de su proyecto. Este archivo puede permitir explícitamente ciertas rutas.
+
+**File**: .ignore
+
+```text
+!node_modules/
+!dist/
+!build/
+```
+
+Por ejemplo, este archivo `.ignore` permite que ripgrep busque dentro de los directorios `node_modules/`, `dist/` y `build/` incluso si figuran en `.gitignore`.

package/.utils/export_opencode_session.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+import sqlite3
+import os
+import json
+import sys
+from datetime import datetime
+
+DB_PATH = "/Users/wavesbyte/.local/share/opencode/opencode.db"
+
+# Escribe aquí el ID de la sesión que deseas exportar (ejemplo: "ses_1234...")
+# Si se deja vacío, el script requerirá el ID como argumento al ejecutarlo
+TARGET_SESSION_ID = "ses_12f8"
+
+
+def format_timestamp(ts):
+    if not ts:
+        return "N/A"
+    try:
+        # DB timestamp is in milliseconds
+        dt = datetime.fromtimestamp(ts / 1000.0)
+        return dt.strftime("%Y-%m-%d %H:%M:%S")
+    except Exception:
+        return str(ts)
+
+def sanitize_filename(name):
+    # Keep only alphanumeric, spaces, hyphens, and underscores
+    return "".join(c for c in name if c.isalnum() or c in (" ", "-", "_")).rstrip().replace(" ", "_")
+
+def get_session_tree(cursor, session_id):
+    """Recursively fetch child sessions and build a flat list with structure info."""
+    cursor.execute("SELECT * FROM session WHERE id = ?", (session_id,))
+    main = cursor.fetchone()
+    if not main:
+        return []
+
+    sessions = []
+
+    def traverse(sid, depth=0):
+        cursor.execute("SELECT * FROM session WHERE id = ?", (sid,))
+        s = cursor.fetchone()
+        if not s:
+            return
+
+        s_dict = dict(s)
+        s_dict['depth'] = depth
+        sessions.append(s_dict)
+
+        # Find children
+        cursor.execute("SELECT id FROM session WHERE parent_id = ? ORDER BY time_created ASC", (sid,))
+        children = cursor.fetchall()
+        for child in children:
+            traverse(child['id'], depth + 1)
+
+    traverse(session_id)
+    return sessions
+
+def export_session_messages(cursor, session, output_dir, file_index):
+    sid = session['id']
+    title = session['title'] or f"Subagent_{sid[:8]}"
+    agent = session['agent'] or "unknown"
+
+    filename = f"{file_index:02d}_{sanitize_filename(title)}.md"
+    filepath = os.path.join(output_dir, filename)
+
+    # Fetch messages and their parts
+    cursor.execute("SELECT * FROM message WHERE session_id = ? ORDER BY time_created ASC", (sid,))
+    messages = cursor.fetchall()
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write(f"# {title}\n\n")
+        f.write(f"* **ID de Sesión**: `{sid}`\n")
+        if session['parent_id']:
+            f.write(f"* **ID Padre**: `{session['parent_id']}`\n")
+        f.write(f"* **Agente**: `{agent}`\n")
+        f.write(f"* **Modelo**: `{session['model']}`\n")
+        f.write(f"* **Creado**: {format_timestamp(session['time_created'])}\n")
+        f.write(f"* **Costo estimado**: ${session['cost'] or 0.0:.6f}\n")
+        f.write(f"* **Tokens**: Entrada: {session['tokens_input'] or 0} | Salida: {session['tokens_output'] or 0} | Razonamiento: {session['tokens_reasoning'] or 0}\n\n")
+        f.write("---\n\n")
+
+        for msg in messages:
+            msg_id = msg['id']
+            msg_data = {}
+            try:
+                msg_data = json.loads(msg['data'])
+            except Exception:
+                pass
+
+            role = msg_data.get('role', 'System')
+            role_emoji = "👤 Usuario" if role == "user" else "🤖 Asistente"
+            f.write(f"## {role_emoji} ({format_timestamp(msg['time_created'])})\n\n")
+
+            # Fetch parts for this message
+            cursor.execute("SELECT * FROM part WHERE message_id = ? ORDER BY time_created ASC", (msg_id,))
+            parts = cursor.fetchall()
+
+            for part in parts:
+                part_data = {}
+                try:
+                    part_data = json.loads(part['data'])
+                except Exception:
+                    continue
+
+                p_type = part_data.get('type')
+
+                if p_type == 'text':
+                    f.write(part_data.get('text', '') + "\n\n")
+
+                elif p_type == 'reasoning':
+                    f.write("<details>\n<summary>💭 Pensamiento (Reasoning)</summary>\n\n")
+                    f.write(part_data.get('text', '') + "\n")
+                    f.write("\n</details>\n\n")
+
+                elif p_type == 'tool':
+                    tool_name = part_data.get('tool', 'unknown')
+                    state = part_data.get('state', {})
+                    status = state.get('status', 'unknown')
+
+                    # Tool Call Input
+                    f.write(f"⚙️ **Llamada a Herramienta**: `{tool_name}` (Estado: *{status}*)\n\n")
+                    tool_input = state.get('input', {})
+                    f.write("```json\n")
+                    f.write(json.dumps(tool_input, indent=2) + "\n")
+                    f.write("```\n\n")
+
+                    # Tool Call Output
+                    tool_output = state.get('output', '')
+                    f.write("📥 **Resultado de la Herramienta**:\n")
+                    try:
+                        parsed_out = json.loads(tool_output)
+                        f.write("```json\n" + json.dumps(parsed_out, indent=2) + "\n```\n\n")
+                    except Exception:
+                        if "\n" in tool_output:
+                            f.write("```\n" + tool_output + "\n```\n\n")
+                        else:
+                            f.write(f"`{tool_output}`\n\n")
+
+        print(f"  Exportado: {filename}")
+    return filename
+
+def list_sessions(cursor):
+    cursor.execute("""
+        SELECT id, title, agent, time_created
+        FROM session
+        WHERE parent_id IS NULL OR parent_id = ''
+        ORDER BY time_created DESC
+        LIMIT 15
+    """)
+    sessions = cursor.fetchall()
+    print("Últimas sesiones de OpenCode disponibles:")
+    print("-" * 85)
+    for s in sessions:
+        title = s['title'] or "(Sin título)"
+        created = format_timestamp(s['time_created'])
+        print(f"ID: {s['id']} | {created} | {s['agent']} - {title[:35]}")
+    print("-" * 85)
+
+def main():
+    if not os.path.exists(DB_PATH):
+        print(f"Error: No se encontró la base de datos de OpenCode en {DB_PATH}")
+        sys.exit(1)
+
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    cursor = conn.cursor()
+
+    target_session_id = TARGET_SESSION_ID
+
+    # If not configured in the script, look for command line arguments
+    if not target_session_id:
+        if len(sys.argv) < 2:
+            list_sessions(cursor)
+            print("\nUso: python3 export_opencode_session.py <session_id>")
+            print("O configura la variable 'TARGET_SESSION_ID' al inicio de este script.")
+            conn.close()
+            sys.exit(0)
+        target_session_id = sys.argv[1]
+
+    # Resolver el ID si es parcial/prefijo (ej. "ses_1619")
+    # Prioriza sesiones raíz (sin padre) para no agarrar un subagente por error
+    cursor.execute("""
+        SELECT id FROM session
+        WHERE id = ? OR id LIKE ?
+        ORDER BY (parent_id IS NULL OR parent_id = '') DESC, time_created DESC
+        LIMIT 1
+    """, (target_session_id, f"{target_session_id}%"))
+    row = cursor.fetchone()
+    if row:
+        target_session_id = row['id']
+
+    # 1. Fetch entire tree
+    session_tree = get_session_tree(cursor, target_session_id)
+
+    if not session_tree:
+        print(f"Error: No se encontró la sesión con ID '{target_session_id}'")
+        conn.close()
+        sys.exit(1)
+
+    main_session = session_tree[0]
+    safe_title = sanitize_filename(main_session['title'] or "session")
+    export_dir_name = f"export_{target_session_id[:8]}_{safe_title}"
+    output_dir = os.path.abspath(export_dir_name)
+
+    os.makedirs(output_dir, exist_ok=True)
+    print(f"\nExportando sesión principal y subagentes a: {output_dir}\n")
+
+    # 2. Export each session
+    exported_files = []
+    for idx, s in enumerate(session_tree):
+        fname = export_session_messages(cursor, s, output_dir, idx)
+        exported_files.append((s, fname))
+
+    # 3. Create README index file
+    readme_path = os.path.join(output_dir, "README.md")
+    with open(readme_path, "w", encoding="utf-8") as f:
+        f.write(f"# Índice de Sesión de OpenCode\n\n")
+        f.write(f"Este directorio contiene los registros completos y ordenados de la sesión y todos sus subagentes.\n\n")
+
+        f.write("## Datos de la Sesión Principal\n")
+        f.write(f"* **ID**: `{main_session['id']}`\n")
+        f.write(f"* **Título**: {main_session['title']}\n")
+        f.write(f"* **Agente Principal**: `{main_session['agent']}`\n")
+        f.write(f"* **Creado**: {format_timestamp(main_session['time_created'])}\n")
+        f.write(f"* **Última Actualización**: {format_timestamp(main_session['time_updated'])}\n\n")
+
+        f.write("## 🌳 Árbol de Ejecución de Subagentes\n")
+        f.write("Haz clic en los enlaces para abrir el historial detallado de cada subagente:\n\n")
+
+        for s, fname in exported_files:
+            indent = "  " * s['depth']
+            bullet = "•" if s['depth'] > 0 else "📂"
+            agent_label = f"({s['agent']})" if s['agent'] else ""
+            title_text = s['title'] or f"Subagente {s['id'][:8]}"
+            f.write(f"{indent}{bullet} [{title_text}]({fname}) {agent_label}\n")
+
+        f.write("\n\n---\n*Exportación generada automáticamente el: {}*\n".format(datetime.now().strftime("%Y-%m-%d %H:%M:%S")))
+
+    print(f"\n¡Listo! Se ha creado un archivo README.md indexado en:\n{readme_path}\n")
+    conn.close()
+
+if __name__ == "__main__":
+    main()