robbin/grokbot-local-agent

Invocar a Pi Agent en el ordenador del Bot

Pi es un agente de codificación por línea de comandos instalado en el ordenador del Bot. Su modelo predeterminado es DeepSeek Flash, con nivel de razonamiento high. Puede leer y escribir archivos, ejecutar comandos y buscar en internet. Para más detalles sobre instalación y configuración, consulta docs/setup-guide.md en el repositorio. Los scripts están en ~/tools/pi-call/ (directorio bin/ del repositorio).

Política de uso

El consumo de modelo del Bot es limitado. Pi utiliza la propia cuenta de modelo del usuario (por defecto DeepSeek), por lo que su cuota es independiente. Las tareas pesadas se delegan por defecto a Pi, mientras que el Bot solo se encarga de la orquestación y supervisión.

Delegar a Pi:

• Procesamiento por lotes de archivos: modificar varios archivos, organizar datos, convertir formatos.
• Escribir código: scripts, herramientas pequeñas, pruebas, depuración.
• Investigación extensa y búsqueda en internet.
• Borradores largos: primera versión de documentos, informes, artículos.
• Cuando el usuario solicite explícitamente que Pi lo haga, pida una segunda opinión o una comparación.

Realiza el Bot:

• Conversaciones cortas y preguntas que se responden en uno o dos pasos.
• Operaciones de conectores (Gmail, X, GitHub, etc.) — Pi no tiene estos conectores.
• Confirmación antes de enviar, publicar, subir o desplegar, y reportar al usuario.

Cómo hacerlo:

• Instrucciones breves: escribe claramente el objetivo, dónde está la entrada, dónde se escribe la salida, y el criterio de finalización. Con unas pocas líneas basta; no pegues grandes fragmentos de texto en el prompt, deja que Pi lea los archivos.
• Guarda los resultados directamente como archivos: especifica la ruta de salida en el prompt para que Pi escriba el archivo. El Bot lo revisa y entrega ese archivo directamente, sin reescribirlo. Si necesita cambios, usa la misma sesión para que Pi los haga.
• Las conclusiones clave deben materializarse: las conclusiones, decisiones o datos importantes que surjan de la tarea deben ser escritos por el Bot en la memoria o en los documentos relevantes, no solo en la sesión de Pi.

Pasos

1. Determina el directorio de trabajo: solo asigna a Pi el directorio necesario para completar la tarea (repositorio o /tmp/<tarea>), no / ni todo el directorio home.
2. Asigna un nombre de sesión: usa kebab-case corto en inglés, un nombre por tarea (ej. news-i18n). Las modificaciones posteriores de la misma tarea usan el mismo nombre; para empezar de cero, cambia el nombre.
3. Define la ubicación de salida: si no hay un lugar más adecuado, usa /tmp/pi-out/<nombre-de-sesión>/; para resultados que deban persistir o sincronizarse, escríbelos directamente donde correspondan (repositorio, documentación o directorio de notas).
4. Escribe el prompt: breve y completo, indicando objetivo, restricciones, ruta del archivo de salida, criterio de finalización. Finalmente, pídele que informe qué archivos escribió y una conclusión en una frase. Pi no ve el historial del chat; proporciona el contexto necesario en una o dos líneas, y para materiales largos, da la ruta del archivo.
5. Invoca la tarea. Para tareas de más de uno o dos minutos, usa siempre pi-task; este asigna un ID de tarea, registra el estado y el progreso, y guarda el resultado como archivo:

   ~/tools/pi-call/pi-task run <directorio-de-trabajo> "<prompt>" --session <nombre-de-sesión> --owner <tu-agent-id> [--timeout segundos] [--no-write] [--no-web]
   

   --owner es obligatorio: asigna la tarea al Bot que la encargó, para que las notificaciones de finalización lleguen al bot correcto. También evita que diferentes bots se apropien de las tareas de otros en pending/ack. Si no se especifica, la tarea se ejecuta igual (owner queda null, stderr muestra una advertencia), pero las notificaciones no se redirigirán. (También se puede definir mediante la variable de entorno PI_TASK_OWNER, pero pasarlo explícitamente es más seguro.) El ID de tu agente se encuentra en tu ruta de perfil (ej. /home/box/agent-data/agents/<tu-agent-id>/profile.json). Usa la ejecución en segundo plano de la herramienta Shell (no bloqueante), no uses nohup, & ni setsid. La primera línea de salida es TASK <ID>. Al finalizar, imprime el estado y la ruta de result.md. Códigos de salida: 0 completado, 1 error, 124 tiempo de espera agotado, 130 cancelado. Otros subcomandos: status <ID> (estado, owner, duración, eventos recientes), log <ID> [-n 30], list [--all] [--owner <id>|none], cancel <ID>, pending [--owner <id>|none] (tareas finalizadas pero no reportadas), ack <ID> [--owner <id>|none] (marca como reportada; rechaza si el owner no coincide; código de salida 1). Los datos de la tarea están en ~/.pi/tasks/<ID>/: status.json, events.jsonl, result.md, prompt-<n>.txt. Si el ordenador del Bot se reinicia, las tareas en ejecución se marcan como interrupted; pregunta al usuario si desea reejecutarlas. Notificación de finalización: Cuando las variables de entorno PI_NOTIFY_URL y PI_NOTIFY_SECRET estén definidas (como variables de entorno del ordenador del Bot, no escritas en archivos), pi-task envía a ese webhook {source, id, owner, state, exit_code} al finalizar cada tarea, sin incluir el contenido de la tarea. La tarea rutinaria que lo recibe, al despertarse, ejecuta pending --owner <su-id>, verifica, reporta y hace ack --owner <su-id>. Solo procesa tareas cuyo owner es él mismo; las tareas de otros bots no se verifican ni se ackean, se reenvían mediante SendToAgent (priority true) al Bot owner; si el entorno de la tarea rutinaria no puede enviar mensajes, se devuelve al Bot principal para reenvío. Las tareas sin owner solo se notifican al usuario, no se ackean. Si no hay configuración, se omite automáticamente y el resultado del envío se registra en el evento notify de events.jsonl. Se puede desactivar temporalmente con PI_NOTIFY_OFF=1. Reporte de respaldo: Es posible que no se reciba la notificación de finalización. Por eso, cada vez que el Bot se despierte (mensaje del usuario, tarea rutinaria, etc.) y tenga tareas asignadas a Pi, primero ejecuta pi-task pending --owner <su-id> para ver solo sus propias tareas. Una vez verificadas las tareas finalizadas pero no reportadas, las entrega y luego hace ack <ID> --owner <su-id>; solo ackea las suyas, las tareas de otros bots se dejan para el Bot que las encargó. Para consultas cortas que puedan completarse en decenas de segundos, se puede invocar directamente en primer plano:

   ~/tools/pi-call/pi-run <directorio-de-trabajo> "<prompt>" --session <nombre-de-sesión> [--timeout segundos]
   

   Para operaciones de solo lectura o para cambiar de modelo, usa el script de bajo nivel:

   ~/tools/pi-call/pi-call.mjs <directorio-de-trabajo> deepseek/deepseek-flash "<prompt>" --thinking high [--allow-write] [--no-web] [--session <nombre-de-sesión>] [--timeout segundos]
   

   pi-run y pi-call.mjs: la salida estándar es solo la última respuesta de Pi; tiempo de espera predeterminado 300 segundos; código de salida 0 éxito, 1 error, 124 tiempo de espera agotado, 127 pi no encontrado. Permisos: pi-task run y pi-run otorgan por defecto todas las herramientas (lectura, búsqueda, ejecución de comandos, escritura de archivos, búsqueda en internet); pi-call.mjs sin --allow-write solo tiene herramientas de solo lectura.
6. Verifica los resultados: la respuesta de Pi es solo su afirmación. Usa git diff, ejecuta pruebas o lee los archivos para confirmar que realmente se hizo, y luego transmite al usuario la conclusión verificada. No tomes conclusiones no verificadas como hechos.
7. Modificaciones posteriores: para tareas de pi-task, usa pi-task reply <ID> "<qué modificar>" (misma sesión, mismo directorio, hereda el owner de la tarea original; se rechaza si la tarea aún se está ejecutando). Para tareas de pi-run, invoca de nuevo con el mismo --session. Las sesiones de ambos se almacenan por separado y no pueden continuarse entre sí.

Reglas

• Se utiliza la cuota de modelo del usuario (la búsqueda en internet consume la cuota de su propio servicio de búsqueda). Invocar solo cuando sea necesario, sin repeticiones sin sentido ni ejecuciones masivas vacías.
• No delegar a Pi: enviar código, desplegar, cambiar DNS o servicios en línea, enviar mensajes o correos, eliminar archivos importantes. Todo esto lo realiza el Bot, previa aprobación del usuario.
• No permitir que Pi lea o escriba ~/.pi/agent/auth.json, archivos de clave secreta ni claves en variables de entorno.
• No ackear tareas de otros: en pending/ack usar siempre --owner <tu-id>; si el owner no coincide, reenviar la tarea al Bot que la encargó.
• En las respuestas visibles para el usuario, indicar “Pi ha hecho X” y explicar qué has verificado.

Solución de problemas

• pi: command not found: Ejecuta primero export PATH=$HOME/.local/bin:$HOME/.node22/bin:$PATH.
• Indica que no hay modelo disponible: la sesión de DeepSeek ha caducado; el usuario debe ejecutar pi en la terminal de su escritorio y luego /login para volver a iniciar sesión. El Bot no puede iniciar sesión por el usuario.
• Tiempo de espera agotado: divide la tarea en partes más pequeñas o aumenta --timeout.
• Error o resultado incorrecto: primero revisa el código de salida y el registro con --verbose; si la tarea en sí está mal, usa la misma sesión para señalar el problema y pedir a Pi que lo rehaga, con un máximo de uno o dos reintentos. Si aún así no funciona, el Bot toma el control e informa al usuario qué no funcionó bien en Pi, sin ejecutar la tarea repetidamente en vano.