@asm-agent/coding-agent 0.9.3 → 0.9.4

package/bundled-extensions/OLLAMA-TOOL-FORCING-IMPLEMENTATION.md

@@ -0,0 +1,323 @@
+# Guia de Implementação - Ollama Tool-Forcing Extension
+
+## 🎯 Objetivo
+
+Forçar modelos abertos (Qwen, Llama, etc) rodando via Ollama a **sempre chamar ferramentas**
+antes de parar, mantendo o loop autônomo do ASM Agent funcionando continuamente.
+
+---
+
+## 📦 O Que Foi Criado
+
+```
+~/.asm-agent/extensions/
+├── ollama-tool-forcing.ts              ← Extensão (implementação)
+├── OLLAMA-TOOL-FORCING.md              ← Manual completo
+├── OLLAMA-TOOL-FORCING-QUICK-START.txt ← Referência rápida
+└── OLLAMA-TOOL-FORCING-TESTS.md        ← Exemplos de teste
+```
+
+### 📋 Tamanho Total: ~18 KB (minúsculo, impacto zero em performance)
+
+---
+
+## 🚀 Instalação (Já Feita!)
+
+A extensão foi colocada automaticamente em:
+```
+~/.asm-agent/extensions/ollama-tool-forcing.ts
+```
+
+ASM Agent a descobrirá automaticamente na próxima inicialização.
+
+### ✅ O que você precisa fazer:
+
+1. **Nada!** Está pronto para usar.
+
+OR
+
+2. Se ASM Agent já está rodando:
+   - Use `/reload` para recarregar extensões
+   - Use `/ollama-tools-info` para verificar se está ativa
+
+---
+
+## 🎮 Como Usar
+
+### Ativação Automática
+
+Quando você inicia o ASM Agent, a extensão:
+1. É auto-descoberta (está em ~/.asm-agent/extensions/)
+2. É carregada automaticamente
+3. Injeta a regra de tool-forcing no system prompt
+4. Funciona em TODAS as requisições
+
+Você não precisa fazer nada especial.
+
+### Verificar Status
+
+```
+/ollama-tools-info
+```
+
+Mostra:
+- Status: ✅ ATIVADO ou ❌ DESATIVADO
+- Permite fazer toggle (ligar/desligar)
+
+### Recarregar (se fizer edições)
+
+```
+/reload
+```
+
+Recompila e recarrega todas as extensões.
+
+---
+
+## 🔧 Como Funciona Internamente
+
+### Fluxo:
+
+```
+1. Você envia um prompt ao ASM Agent
+    ↓
+2. ASM Agent prepara o system prompt
+    ↓
+3. EXTENSÃO intercepta via before_agent_start
+    ↓
+4. Extensão adiciona a regra de tool-forcing
+    ↓
+5. Modelo recebe: system_prompt + regra_de_forcing
+    ↓
+6. Modelo fica "forçado" a chamar ferramentas
+    ↓
+7. Loop autônomo continua até completar tarefa
+```
+
+### Regra Injetada:
+
+```
+## ⚠️ REGRA CRÍTICA: TOOL-FORCING PARA MODELOS LOCAIS
+
+Você está rodando num modelo aberto (Ollama/local). Para garantir que trabalhe autonomamente:
+
+1. NUNCA pare sem chamar uma ferramenta
+2. Sem gerações vazias
+3. Ferramentas = continuidade
+4. Padrão: pensar → agir → observar → repetir
+5. Proibido terminar sem chamar ferramenta
+```
+
+---
+
+## 🧪 Teste Rápido
+
+Rode isto no ASM Agent com seu Qwen/Llama via Ollama:
+
+```
+Crie um arquivo test.txt com "Olá!" e depois exiba seu conteúdo com bash.
+```
+
+**Resultado esperado:**
+- Modelo chama edit para criar
+- Modelo chama bash para exibir
+- Modelo reporta sucesso
+- Não fica preso
+
+---
+
+## ⚙️ Personalização
+
+### Editar a Regra
+
+Para mudar o tom, adicionar regras, etc:
+
+```bash
+nano ~/.asm-agent/extensions/ollama-tool-forcing.ts
+```
+
+Modifique a seção `const toolForceRule = ...`
+
+Depois use `/reload` para aplicar.
+
+### Criar Variantes
+
+Para diferentes comportamentos:
+
+```bash
+# Cópia para projeto local
+cp ~/.asm-agent/extensions/ollama-tool-forcing.ts .asm-agent/extensions/
+# Edite conforme necessário
+```
+
+ASM Agent prioriza extensões locais (.asm-agent/) sobre globais (~/.asm-agent/).
+
+### Desativar Temporariamente
+
+Use o comando:
+```
+/ollama-tools-info
+```
+
+Faz toggle entre ✅ e ❌ sem reiniciar.
+
+### Remover Permanentemente
+
+```bash
+rm ~/.asm-agent/extensions/ollama-tool-forcing.ts
+/reload
+```
+
+---
+
+## 🎯 Casos de Uso
+
+### ✅ USE QUANDO:
+
+- Rodando **Qwen 27b/32b** via Ollama
+- Rodando **Llama** via Ollama  
+- Qualquer **modelo aberto local**
+- Modelo que **às vezes congela**
+- Quer **loop autônomo garantido**
+- Quer **evitar gerações vazias**
+
+### ❌ PODE DESATIVAR QUANDO:
+
+- Rodando **Claude/GPT** (APIs cloud)
+- Modelo está **funcionando bem** já
+- Quer testar **comportamento natural**
+- Rodando teste que espera modelo parar naturalmente
+
+Use `/ollama-tools-info` para toggle sem reiniciar.
+
+---
+
+## 🐛 Troubleshooting
+
+| Problema | Causa | Solução |
+|----------|-------|---------|
+| Extensão não carrega | Erro TypeScript | Verifique sintaxe em ollama-tool-forcing.ts |
+| Modelo ainda fica preso | Extensão não foi recarregada | Use `/reload` depois de iniciar |
+| Regra muito agressiva | Instrução forte demais | Edite e suavize o tom |
+| Funciona às vezes | Dependente do prompt | Teste com prompts mais específicos |
+
+---
+
+## 📊 Benchmarks Esperados
+
+### COM A EXTENSÃO:
+
+```
+Tarefa: Criar arquivo + editar + verificar
+
+Tempo: ~10-30 segundos
+Chamadas: modelo → bash/edit/ipython → modelo → ... → completo
+Resultado: ✅ Tarefa completada autonomamente
+```
+
+### SEM A EXTENSÃO (Qwen/Llama pequeno):
+
+```
+Tarefa: Criar arquivo + editar + verificar
+
+Tempo: ~5-10 segundos
+Chamadas: modelo → pensar → PARAR
+Resultado: ❌ Aguardando sua resposta "e aí?"
+```
+
+A extensão sacrifica um pouco de velocidade pelo ganho MASSIVO de confiabilidade.
+
+---
+
+## 🔐 Segurança
+
+A extensão:
+- ✅ Não executa código seu (apenas injeta texto no prompt)
+- ✅ Não altera ferramentas existentes
+- ✅ Não acessa arquivos/rede
+- ✅ É 100% local
+- ✅ Pode ser auditada (arquivo texto simples)
+
+---
+
+## 📚 Documentação Relacionada
+
+- **Manual Completo**: OLLAMA-TOOL-FORCING.md
+- **Quick Start**: OLLAMA-TOOL-FORCING-QUICK-START.txt
+- **Testes**: OLLAMA-TOOL-FORCING-TESTS.md
+- **Extensões (ASM Agent)**: ~/dev/ai/asm-agent/packages/coding-agent/examples/extensions/
+
+---
+
+## 🎓 Aprendizados
+
+### Por Que Modelos Menores Congelam
+
+Modelos como Qwen 27b (vs Claude 3.5, GPT-4):
+- Não foram treinados tão bem em tool-calling
+- Podem confundir o formato de chamada de ferramenta
+- Podem não entender que devem chamar uma ferramenta
+- Podem gerar um "stop token" por default
+
+### Como Essa Extensão Resolve
+
+Ela:
+1. Intercepta ANTES do modelo pensar
+2. Injeta uma instrução MUITO CLARA e FORTE
+3. Torna PROIBIDO parar sem ferramentas
+4. Força o modelo a "obedecer" via prompt engineering
+
+Não é uma "fix" técnica real — é uma "fix" por prompt.
+
+---
+
+## 🚀 Próximos Passos
+
+1. **Inicialize ASM Agent** (a extensão carrega automaticamente)
+2. **Teste com uma tarefa simples** (criar arquivo + verificar)
+3. **Observe o modelo chamar ferramentas continuamente**
+4. **Ajuste se necessário** usando `/ollama-tools-info` ou edições
+
+---
+
+## 💡 Dicas Pro
+
+### Combine com Qwen Coder
+
+```bash
+ollama pull qwen2.5-coder:32b
+# MUITO melhor em tool-calling
+```
+
+### Combine com Atualização Ollama
+
+```bash
+ollama --version
+# Atualize se < 0.1.20 (versões antigas engolem tool calls)
+```
+
+### Combine com Outras Extensões
+
+Você pode ter múltiplas extensões simultaneamente:
+- ollama-tool-forcing.ts (sua nova regra)
+- git-checkpoint.ts (backup automático)
+- permission-gate.ts (confirmação antes de rm -rf)
+- etc
+
+Copie exemplos de:
+~/dev/ai/asm-agent/packages/coding-agent/examples/extensions/
+
+---
+
+## 📞 Suporte
+
+Se tiver dúvidas:
+
+1. Leia: OLLAMA-TOOL-FORCING.md
+2. Teste: OLLAMA-TOOL-FORCING-TESTS.md
+3. Edite: ollama-tool-forcing.ts (é um arquivo simples)
+4. Recarregue: /reload
+
+---
+
+✨ **Tudo pronto! Sua Custom Rule está funcionando.** ✨

package/bundled-extensions/OLLAMA-TOOL-FORCING-QUICK-START.txt

@@ -0,0 +1,113 @@
+
+╔════════════════════════════════════════════════════════════════════════════════╗
+║                   ✅ CUSTOM RULE CRIADA COM SUCESSO!                          ║
+║              Ollama Tool-Forcing Extension para ASM Agent                      ║
+╚════════════════════════════════════════════════════════════════════════════════╝
+
+📦 ARQUIVO CRIADO:
+   ~/.asm-agent/extensions/ollama-tool-forcing.ts
+
+📖 DOCUMENTAÇÃO:
+   ~/.asm-agent/extensions/OLLAMA-TOOL-FORCING.md
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 O QUE FAZ:
+
+A extensão **força automaticamente** modelos open-weights (Qwen, Llama, etc)
+rodando via Ollama a:
+
+  ✅ NUNCA parar sem chamar uma ferramenta
+  ✅ Chamar bash/edit/ipython para continuar trabalho
+  ✅ Manter o loop autônomo do ASM Agent funcionando
+  ✅ Evitar gerações "vazias" que congelam sessões
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🚀 COMO USAR:
+
+1️⃣  A extensão é auto-descoberta
+   Ela será carregada automaticamente na próxima sessão
+
+2️⃣  Para ativar já em sessão aberta, use:
+   /reload
+
+3️⃣  Para verificar status e fazer toggle:
+   /ollama-tools-info
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 SYSTEM PROMPT INJETADO:
+
+A extensão adiciona automaticamente esta regra ao final do system prompt:
+
+   ## ⚠️ REGRA CRÍTICA: TOOL-FORCING PARA MODELOS LOCAIS
+
+   1. NUNCA pare sem chamar uma ferramenta
+   2. Sem gerações vazias (só thinking não é permitido)
+   3. Ferramentas = continuidade (use bash, edit, ipython constantemente)
+   4. Padrão: pensar → agir → observar → repetir
+   5. Proibido terminar sem chamar ferramenta
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+⚙️  PERSONALIZAÇÕES OPCIONAIS:
+
+Você pode editar o arquivo para:
+   • Mudar o tom da instrução
+   • Adicionar regras específicas do seu workflow
+   • Desabilitar para certos tipos de tarefas
+   • Adicionar logging de quando a regra foi aplicada
+
+   Edite: ~/.asm-agent/extensions/ollama-tool-forcing.ts
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📚 DOCUMENTAÇÃO COMPLEMENTAR:
+
+Para mais detalhes, leia:
+   ~/.asm-agent/extensions/OLLAMA-TOOL-FORCING.md
+
+Contém:
+   • Explicação detalhada do problema
+   • Quando usar/não usar
+   • Dicas de otimização (Qwen Coder, versão Ollama, etc)
+   • Como remover se necessário
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔧 RELACIONADO:
+
+Se quiser mais controle, você também pode:
+
+1. Usar --system-prompt flag ao iniciar ASM Agent
+2. Criar um arquivo SYSTEM.md no projeto
+3. Usar múltiplas extensões juntas
+4. Combinar com outras regras (permission-gate, git-checkpoint, etc)
+
+Veja exemplos em:
+   ~/dev/ai/asm-agent/packages/coding-agent/examples/extensions/
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✨ RESUMO DO CICLO:
+
+ANTES (problema):
+  Modelo → pensa → para → ASM Agent aguarda → você fica preso
+
+DEPOIS (com a extensão):
+  Modelo → pensa → chama bash → observa resultado → pensa novamente
+  → chama edit/ipython → continua autônomo até completar tarefa
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎬 PRÓXIMOS PASSOS:
+
+1. Reinicie o ASM Agent (a extensão será carregada automaticamente)
+2. Rode uma tarefa com seu Qwen/Llama via Ollama
+3. Observe o modelo sendo forçado a chamar ferramentas constantemente
+4. Se quiser desativar, use /ollama-tools-info ou delete o arquivo
+
+╔════════════════════════════════════════════════════════════════════════════════╗
+║               🎉 Extensão pronta! Teste agora com seu modelo!                  ║
+╚════════════════════════════════════════════════════════════════════════════════╝

package/bundled-extensions/OLLAMA-TOOL-FORCING-TESTS.md

@@ -0,0 +1,217 @@
+# Exemplos de Teste - Ollama Tool-Forcing Extension
+
+Após ativar a extensão, teste com estes comandos no ASM Agent.
+
+## Teste 1: Tarefa Simples com Verificação
+
+```
+Crie um arquivo chamado "test.txt" com o texto "Olá, Ollama!" e depois verifique 
+o conteúdo usando bash.
+```
+
+**Resultado esperado:**
+- Modelo vai pensar
+- Modelo chama bash/edit para criar arquivo
+- Modelo chama bash para verificar conteúdo
+- Modelo continua até completar (não fica preso)
+
+---
+
+## Teste 2: Script Python
+
+```
+Escreva um script Python que imprime "Hello" 10 vezes e depois execute-o.
+Mostre os resultados.
+```
+
+**Resultado esperado:**
+- Modelo chama edit para criar o script
+- Modelo chama bash (ou ipython) para rodar
+- Modelo observa saída e confirma sucesso
+- Loop completo
+
+---
+
+## Teste 3: Navegação de Projeto
+
+```
+Você está no diretório atual. Liste os arquivos do diretório pai usando bash,
+analise quantos são diretórios vs arquivos, e reporte os dados.
+```
+
+**Resultado esperado:**
+- Modelo chama bash (pwd, ls, etc)
+- Modelo processa informação
+- Modelo chama bash novamente se precisar de mais dados
+- Completa a análise
+
+---
+
+## Teste 4: Édição de Arquivo Múltipla
+
+```
+1. Crie um arquivo chamado "config.json" com objeto vazio {}
+2. Adicione um campo "version": "1.0"
+3. Adicione um campo "name": "test-app"
+4. Verifique o resultado final
+```
+
+**Resultado esperado:**
+- Modelo chama edit para criar
+- Modelo chama edit novamente para adicionar campos
+- Modelo chama bash para verificar
+- Nunca fica preso entre passos
+
+---
+
+## Teste 5: Loop Autônomo Completo
+
+```
+Implemente uma função em Python que:
+1. Calcula o fatorial de 5
+2. Verifica se o resultado é par ou ímpar
+3. Escreve o resultado em um arquivo
+4. Lê o arquivo para confirmar
+
+Faça tudo isso automaticamente sem parar.
+```
+
+**Resultado esperado:**
+- Modelo chama ipython/edit múltiplas vezes
+- Modelo usa bash para ler arquivo
+- Modelo continua autonomamente
+- Completa TODOS os passos sem intervenção
+
+---
+
+## Como Verificar se Está Funcionando
+
+### ✅ Sinais de SUCESSO:
+
+```
+[Thinking: ... análise do problema ...]
+[Tool Call: bash - pwd]
+[Tool Call: edit - criar arquivo]
+[Tool Call: bash - verificar]
+[Thinking: ... análise dos resultados ...]
+Tarefa completada! Aqui estão os resultados...
+```
+
+Há uma **sequência clara** de: pensar → agir → observar → repetir
+
+### ❌ Sinais de PROBLEMA:
+
+```
+[Thinking: ... análise do problema ...]
+[Esperando sua resposta...]
+```
+
+Se o modelo apenas faz **thinking** e para, a extensão não está funcionando.
+
+---
+
+## Comandos Úteis Durante Testes
+
+```bash
+# Ver status da extensão
+/ollama-tools-info
+
+# Recarregar extensões se fizer edições
+/reload
+
+# Ver informações do sistema prompt
+/ollama-tools-info
+```
+
+---
+
+## Ajustes Se Não Funcionar
+
+Se o modelo ainda ficar preso:
+
+### Opção 1: Instrução Manual
+
+```
+"Está tudo bem com o andamento? Chame uma ferramenta (bash ou ipython) para 
+continuar verificando o progresso e avançar a tarefa."
+```
+
+### Opção 2: Usar Qwen Coder
+
+```bash
+ollama pull qwen2.5-coder:32b
+ollama run qwen2.5-coder:32b
+```
+
+A versão Coder é muito melhor em tool-calling.
+
+### Opção 3: Atualizar Ollama
+
+```bash
+ollama --version
+# Se versão antiga, atualize
+```
+
+### Opção 4: Editar a Extensão
+
+Se quiser fazer a regra ainda mais forte, edite:
+```
+~/.asm-agent/extensions/ollama-tool-forcing.ts
+```
+
+E aumente o "peso" da instrução ou adicione consequências explícitas.
+
+---
+
+## Dicas de Debug
+
+### Ver logs:
+
+```bash
+# Se algo falhar na compilação da extensão
+tail -f ~/.asm-agent/logs/*  # (se existir)
+```
+
+### Verificar se o arquivo está correto:
+
+```bash
+ls -la ~/.asm-agent/extensions/ollama-tool-forcing.ts
+wc -l ~/.asm-agent/extensions/ollama-tool-forcing.ts
+```
+
+### Recarregar sem reiniciar:
+
+```
+/reload
+```
+
+Isso recompila e carrega todas as extensões.
+
+---
+
+## Problemas Comuns
+
+| Problema | Solução |
+|----------|---------|
+| Modelo ainda fica preso | Tente `/reload`, depois teste novamente |
+| Extensão não carrega | Verifique sintaxe TypeScript do arquivo |
+| Tool-forcing muito agressivo | Edite o arquivo e suavize o tom |
+| Funciona em alguns casos mas não outros | Pode ser dependente do modelo/prompt |
+
+---
+
+## Para Mais Ajuda
+
+Leia o arquivo completo:
+```
+~/.asm-agent/extensions/OLLAMA-TOOL-FORCING.md
+```
+
+Ou veja exemplos de outras extensões:
+```
+~/dev/ai/asm-agent/packages/coding-agent/examples/extensions/
+```
+
+---
+
+**Boa sorte! 🚀**