robbin/grokbot-local-agent

Chamar o Pi Agent no Computador do Bot

Pi é um agente de codificação de linha de comando instalado no computador do Bot, com modelo padrão DeepSeek Flash, nível de pensamento 'high', capaz de ler/escrever arquivos, executar comandos e pesquisar na web. Detalhes de instalação e configuração estão no arquivo docs/setup-guide.md do repositório. Os scripts estão em ~/tools/pi-call/ (diretório bin/ do repositório).

Estratégia de Uso

O modelo do Bot tem uso limitado; o Pi usa a própria conta de modelo do usuário (padrão DeepSeek), com cotações separadas do Bot. Portanto, tarefas pesadas são delegadas ao Pi por padrão, enquanto o Bot apenas coordena e supervisiona.

Delegar ao Pi:

• Processamento em lote de arquivos: modificar vários arquivos, organizar dados, converter formatos.
• Escrever código: scripts, ferramentas pequenas, testes, depuração.
• Pesquisas longas e busca na web.
• Rascunhos extensos: primeira versão de documentos, relatórios, artigos.
• Quando o usuário pede explicitamente para o Pi fazer, quer uma segunda opinião ou uma comparação sobre o mesmo tópico.

O Bot faz sozinho:

• Conversas curtas e perguntas que podem ser respondidas em uma ou duas etapas.
• Operações de conectores (Gmail, X, GitHub, etc.) – o Pi não tem esses acessos.
• Confirmações antes de enviar, publicar, fazer push ou deploy, e relatar ao usuário.

Como fazer:

• Instruções curtas: escreva claramente o objetivo, onde está a entrada, em qual arquivo salvar a saída e o critério de conclusão. Algumas linhas bastam; não cole textos longos no prompt – deixe o Pi ler os arquivos.
• Resultados direto em arquivo: especifique o caminho de saída no prompt para o Pi escrever o arquivo; o Bot verifica e entrega esse arquivo diretamente, sem reescrevê-lo. Se precisar de alterações, use a mesma sessão para o Pi modificar.
• Conclusões importantes devem ser registradas: conclusões, decisões ou dados relevantes devem ser escritos pelo Bot na memória ou documentos relacionados, não apenas na sessão do Pi.

Passos

1. Determinar o diretório de trabalho: forneça apenas o diretório necessário para a tarefa (repositório ou /tmp/<tarefa>), não / ou todo o diretório home.
2. Nomear a sessão: use kebab-case curto em inglês, um nome por tarefa (ex.: news-i18n). Modificações subsequentes da mesma tarefa reutilizam o mesmo nome; para começar do zero, use um novo nome.
3. Definir local de saída: quando não houver destino mais adequado, use /tmp/pi-out/<nome-da-sessão>/; para resultados que devem ser salvos ou sincronizados, escreva diretamente no local apropriado (repositório, diretório de documentação ou anotações).
4. Escrever o prompt: curto e completo, explicando objetivo, restrições, caminho do arquivo de saída e critério de conclusão. No final, peça para informar quais arquivos foram escritos e uma conclusão de uma linha. O Pi não vê o histórico do chat; forneça contexto necessário em uma ou duas frases e, para materiais longos, dê o caminho do arquivo.
5. Chamar. Para tarefas com duração superior a um ou dois minutos, use sempre pi-task – ele atribui um ID à tarefa, registra o status e o progresso, e salva o resultado em arquivo:

   ~/tools/pi-call/pi-task run <diretório-de-trabalho> "<prompt>" --session <nome-da-sessão> --owner <seu-agent-id> [--timeout segundos] [--no-write] [--no-web]
   

   --owner é obrigatório: ele associa a tarefa ao Bot que a criou, para que notificações de conclusão encontrem o responsável, e pending/ack evitam que bots diferentes disputem para relatar ou reconhecer tarefas uns dos outros. Sem ele, a tarefa ainda executa (owner fica null e um aviso vai para stderr), mas as notificações não retornam. (Também pode ser definido pela variável de ambiente PI_TASK_OWNER, mas passar explicitamente é mais seguro.) O ID do seu agente está no caminho do seu perfil (ex.: /home/box/agent-data/agents/<seu-agent-id>/profile.json). Use a execução em segundo plano fornecida pela ferramenta Shell (não bloqueante), não use nohup, & ou setsid. A primeira linha da saída é TASK <ID da tarefa>; ao final, imprime o status e o caminho do result.md. Códigos de saída: 0 sucesso, 1 falha, 124 timeout, 130 cancelado. Outros subcomandos: status <ID> (status, owner, duração, eventos recentes), log <ID> [-n 30], list [--all] [--owner <id>|none], cancel <ID>, pending [--owner <id>|none] (tarefas concluídas mas ainda não relatadas), ack <ID> [--owner <id>|none] (marca como relatada; rejeita se owner não corresponder, código de saída 1). Dados da tarefa em ~/.pi/tasks/<ID da tarefa>/: status.json, events.jsonl, result.md, prompt-<n>.txt. Se o computador do Bot reiniciar, tarefas ainda em execução são marcadas como interrupted – pergunte ao usuário se deve reexecutar. Notificação de conclusão: Quando as variáveis de ambiente PI_NOTIFY_URL e PI_NOTIFY_SECRET estiverem configuradas (armazenadas como variáveis de ambiente do computador do Bot, não em arquivos), pi-task envia um webhook a cada tarefa concluída com {source, id, owner, state, exit_code}, sem o conteúdo da tarefa. A tarefa de rotina que recebe isso é acionada, executa pending --owner <próprio id>, verifica, relata e ack --owner <próprio id>. Processa apenas tarefas cujo owner é o próprio; tarefas de outros bots não são verificadas nem reconhecidas – usa SendToAgent (priority true) para encaminhar ao Bot dono; se o ambiente da tarefa de rotina não puder enviar mensagens, retorna para o Bot principal encaminhar. Tarefas sem owner apenas notificam o usuário, sem ack. Se não configurado, pula automaticamente e registra o envio no evento notify em events.jsonl; defina PI_NOTIFY_OFF=1 para desligar temporariamente. Relatório de contingência: A notificação de conclusão pode não chegar. Portanto, toda vez que for acordado (mensagem do usuário, tarefa de rotina, etc.) e houver tarefas delegadas ao Pi, execute primeiro pi-task pending --owner <seu id> para ver apenas as tarefas que você criou. Verifique as concluídas mas não relatadas, entregue os resultados e então ack <ID> --owner <seu id>. Reconheça apenas as suas; tarefas de outros bots deixe para o Bot que as criou. Para perguntas curtas que podem ser concluídas em dezenas de segundos, use chamada síncrona direta:

   ~/tools/pi-call/pi-run <diretório-de-trabalho> "<prompt>" --session <nome-da-sessão> [--timeout segundos]
   

   Para operações somente leitura ou troca de modelo, use o script subjacente:

   ~/tools/pi-call/pi-call.mjs <diretório-de-trabalho> deepseek/deepseek-flash "<prompt>" --thinking high [--allow-write] [--no-web] [--session <nome-da-sessão>] [--timeout segundos]
   

   pi-run e pi-call.mjs: saída padrão apenas com a última resposta do Pi; timeout padrão 300 segundos; código de saída 0 sucesso, 1 erro, 124 timeout, 127 Pi não encontrado. Permissões: pi-task run e pi-run liberam todas as ferramentas por padrão (ler, pesquisar, executar comandos, escrever arquivos, buscar na web); pi-call.mjs sem --allow-write tem apenas ferramentas de leitura.
6. Verificar o resultado: a resposta do Pi é apenas o que ele diz. Use git diff, execute testes ou leia os arquivos para confirmar que ele realmente fez o que foi pedido, e então relate ao usuário; não apresente conclusões não verificadas como fatos.
7. Modificar novamente: Para tarefas do pi-task, use pi-task reply <ID da tarefa> "<o que mudar>" (mesma sessão, mesmo diretório, mantém o owner original; se a tarefa ainda estiver em execução, será rejeitada); para tarefas do pi-run, chame novamente com o mesmo --session. As sessões de ambos são armazenadas separadamente e não podem ser continuadas entre si.

Regras

• Usa a cota de modelo do próprio usuário (a busca na web usa a cota do serviço de busca do usuário); chame sob demanda, sem repetições sem sentido ou execuções em lote vazias.
• Push de código, deploy, alteração de DNS ou serviços online, envio de mensagens ou e-mails, exclusão de arquivos importantes – nada disso é delegado ao Pi; o Bot faz essas ações e sempre obtém consentimento do usuário.
• Não permita que o Pi leia ou exiba ~/.pi/agent/auth.json, arquivos de chave ou chaves em variáveis de ambiente.
• Não reconheça tarefas de outros bots: pending/ack sempre com --owner <seu id>; se o owner não corresponder, encaminhe ao Bot que criou.
• Nas respostas visíveis ao usuário, diga "deixei o Pi fazer X" e explique o que você verificou.

Solução de Problemas

• pi: command not found: primeiro export PATH=$HOME/.local/bin:$HOME/.node22/bin:$PATH.
• Aviso de modelo indisponível: login do DeepSeek expirou – o usuário precisa executar pi no terminal da área de trabalho e fazer /login novamente; o Bot não pode fazer login pelo usuário.
• Timeout: divida a tarefa em partes menores ou aumente --timeout.
• Erro ou resultado incorreto: primeiro verifique o código de saída e o log --verbose; se a tarefa em si estiver errada, use a mesma sessão para apontar o problema e pedir que o Pi refaça, no máximo uma ou duas tentativas. Se ainda assim não funcionar, o Bot assume e informa ao usuário onde o Pi falhou – não fique reexecutando sem propósito.