@asm-agent/coding-agent 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [0.9.4] - 2026-09-06
+
+- Added bundled Ollama Tool-Forcing extension that is automatically installed to `~/.asm-agent/extensions/` during setup. This extension helps local open-weight models (Qwen, Llama, etc.) maintain the autonomous loop by forcing tool calls before stopping.
+
 ## [0.9.2] - 2026-09-04
 
 - Fixed the installer hiding download progress for the large ASM-CM package; exposed bytes, speed and remaining time, and added connection and stalled-transfer timeouts.

package/bundled-extensions/00-COMECE-AQUI.txt

@@ -0,0 +1,233 @@
+
+╔════════════════════════════════════════════════════════════════════════════════╗
+║                       ✅ COMECE A USAR AGORA!                                 ║
+║                     Guia de Primeiros Passos (2 minutos)                       ║
+╚════════════════════════════════════════════════════════════════════════════════╝
+
+CENÁRIO 1: ASM Agent não está rodando
+─────────────────────────────────────
+
+1. Abra terminal
+2. Inicie ASM Agent normalmente:
+   $ ./asm-agent.sh
+   
+3. A extensão será carregada automaticamente (já está em ~/.asm-agent/extensions/)
+
+4. Teste com um comando simples:
+   > Crie um arquivo test.txt com "Olá!" e verifique com bash.
+
+5. Observe o modelo chamar ferramentas continuamente ✅
+
+
+CENÁRIO 2: ASM Agent já está rodando
+─────────────────────────────────────
+
+1. No prompt do ASM Agent, digite:
+   /reload
+
+2. Aguarde a recarga de extensões (deve acontecer em segundos)
+
+3. Verifique se está ativo:
+   /ollama-tools-info
+
+   Deve mostrar: ✅ ATIVADO
+
+4. Teste com uma tarefa:
+   > Crie um arquivo test.txt com "Olá!" e verifique com bash.
+
+5. A extensão já está forçando ferramentas! ✅
+
+
+CENÁRIO 3: Quer testar múltiplas vezes
+──────────────────────────────────────
+
+Use os 5 exemplos em OLLAMA-TOOL-FORCING-TESTS.md:
+
+1. Tarefa Simples (criar arquivo + verificar)
+2. Script Python (escrever + executar)
+3. Navegação de Projeto (listar + analisar)
+4. Édição Múltipla (criar + editar 2x + verificar)
+5. Loop Autônomo Completo (cálculo + condicional + arquivo + leitura)
+
+Copie/cole cada um e observe o padrão de chamadas de ferramentas.
+
+
+COMO FUNCIONA (Visual)
+──────────────────────
+
+Fluxo com a extensão ativada:
+
+┌─────────────┐
+│  Seu prompt │
+└──────┬──────┘
+       │
+       ▼
+┌────────────────────────┐
+│ ASM Agent prepara      │
+│ system prompt          │
+└──────┬─────────────────┘
+       │
+       ▼
+┌────────────────────────────────────────────────┐
+│ EXTENSÃO intercepta (before_agent_start)       │
+│ ✅ Injeta regra de tool-forcing no prompt      │
+└──────┬─────────────────────────────────────────┘
+       │
+       ▼
+┌────────────────────────────────────────────────┐
+│ Modelo recebe:                                 │
+│ = seu system prompt                            │
+│ + regra CRÍTICA: "NUNCA PARE SEM FERRAMENTAS" │
+└──────┬─────────────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────────────────┐
+│ Modelo é FORÇADO a:                                 │
+│ 1. Pensar/raciocinar                               │
+│ 2. SEMPRE chamar uma ferramenta (bash/edit/ipython)│
+│ 3. Observar resultado                              │
+│ 4. Repetir até completar tarefa                    │
+└──────┬────────────────────────────────────────────┘
+       │
+       ▼
+┌────────────────────────────┐
+│ ✅ Tarefa completada       │
+│ ✅ Sem interrupções        │
+│ ✅ Loop autônomo funcionou │
+└────────────────────────────┘
+
+
+DICAS QUICK WIN
+───────────────
+
+Quer usar a extensão com máximo desempenho?
+
+1. Use Qwen Coder (muito melhor que Qwen normal):
+   $ ollama pull qwen2.5-coder:32b
+   $ ollama run qwen2.5-coder:32b
+
+2. Atualize Ollama (versões antigas engolem tool calls):
+   $ ollama --version
+
+3. Combine com outras extensões se quiser (git-checkpoint, permission-gate, etc)
+
+4. Se o modelo ficar preso mesmo assim, edite a extensão para aumentar a força:
+   $ nano ~/.asm-agent/extensions/ollama-tool-forcing.ts
+   $ /reload
+
+
+VERIFICAÇÃO RÁPIDA
+──────────────────
+
+Após usar /reload ou reiniciar:
+
+✅ Verdes esperados:
+   • /ollama-tools-info mostra status
+   • Modelo chama bash/edit/ipython constantemente
+   • Tarefas completam sem você precisar falar "e aí?"
+   • Cada turno tem: thinking → tool call → resultado → thinking...
+
+❌ Vermelhos significam problema:
+   • Modelo ainda fica preso após /reload
+   • /ollama-tools-info não responde
+   • Extensão não carrega
+
+   Solução: Verifique OLLAMA-TOOL-FORCING.md seção Troubleshooting
+
+
+DESATIVAR SE PRECISAR
+────────────────────
+
+Temporariamente:
+   /ollama-tools-info    (faz toggle)
+
+Permanentemente:
+   $ rm ~/.asm-agent/extensions/ollama-tool-forcing.ts
+   $ /reload
+
+
+ARQUIVOS DE REFERÊNCIA
+──────────────────────
+
+Local: ~/.asm-agent/extensions/
+
+1. ollama-tool-forcing.ts
+   → A extensão (TypeScript, 3 KB)
+   → Injeta regra no system prompt
+   
+2. OLLAMA-TOOL-FORCING.md
+   → Manual completo (quando tiver dúvidas)
+   
+3. OLLAMA-TOOL-FORCING-QUICK-START.txt
+   → Resumo visual (este arquivo é similar)
+   
+4. OLLAMA-TOOL-FORCING-TESTS.md
+   → 5 testes práticos
+   → Verificação de funcionamento
+   
+5. OLLAMA-TOOL-FORCING-IMPLEMENTATION.md
+   → Como funciona internamente
+   → Customizações avançadas
+
+
+PRÓXIMAS AÇÕES (em ordem)
+─────────────────────────
+
+1️⃣  [ ] Inicie ASM Agent ou /reload
+2️⃣  [ ] Teste com: "Crie test.txt com 'Olá!' e verifique com bash"
+3️⃣  [ ] Observe o modelo chamar ferramentas
+4️⃣  [ ] Teste os 5 exemplos em OLLAMA-TOOL-FORCING-TESTS.md
+5️⃣  [ ] Customize se necessário (editar extensão)
+6️⃣  [ ] Aproveite o loop autônomo funcionando! 🎉
+
+
+PERGUNTAS FREQUENTES
+────────────────────
+
+P: "A extensão funciona com modelos online (Claude, GPT)?"
+R: Funciona, mas não é necessária. Eles já têm tool-calling robusto.
+
+P: "Quanto overhead adiciona?"
+R: ~3 KB, zero impacto perceptível. Apenas injeta texto no prompt.
+
+P: "Posso usar com outras extensões?"
+R: Sim! Múltiplas extensões funcionam juntas.
+
+P: "Se o modelo fica preso mesmo assim?"
+R: Edite a extensão para aumentar "peso" da regra, ou use Qwen Coder.
+
+P: "Como remover se não gostar?"
+R: rm ~/.asm-agent/extensions/ollama-tool-forcing.ts && /reload
+
+P: "Posso modificar a regra?"
+R: Sim! Edite ollama-tool-forcing.ts, depois /reload
+
+
+SUPPORT
+───────
+
+Leia em ordem:
+
+1. OLLAMA-TOOL-FORCING-QUICK-START.txt (este é um similar)
+2. OLLAMA-TOOL-FORCING.md (manual completo)
+3. OLLAMA-TOOL-FORCING-TESTS.md (exemplos práticos)
+4. OLLAMA-TOOL-FORCING-IMPLEMENTATION.md (detalhes técnicos)
+
+
+═══════════════════════════════════════════════════════════════════════════════
+
+🎬 COMECE AGORA!
+
+Se seu ASM Agent está rodando:
+    /reload
+
+Se não está:
+    ./asm-agent.sh
+
+Depois teste:
+    "Crie um arquivo test.txt com conteúdo 'Olá Ollama!' e use bash para
+    verificar que foi criado corretamente."
+
+Aproveite! ✨
+
+═══════════════════════════════════════════════════════════════════════════════

package/bundled-extensions/00-INDEX.md

@@ -0,0 +1,267 @@
+# 📑 ÍNDICE - Ollama Tool-Forcing Extension
+
+## 📂 Localização
+
+Todos os arquivos estão em:
+```
+~/.asm-agent/extensions/
+```
+
+---
+
+## 📋 Lista de Arquivos (em ordem de importância)
+
+### 🚀 COMECE AQUI (prioritário)
+
+| Arquivo | Tamanho | Tempo | Objetivo |
+|---------|---------|-------|----------|
+| **00-COMECE-AQUI.txt** | 8.7 KB | 2 min | Guia rápido de primeiros passos |
+| **ollama-tool-forcing.ts** | 3.2 KB | - | Extensão principal (TypeScript) |
+
+---
+
+### 📚 DOCUMENTAÇÃO COMPLETA
+
+| Arquivo | Tamanho | Tempo | Objetivo |
+|---------|---------|-------|----------|
+| **OLLAMA-TOOL-FORCING.md** | 4.4 KB | 25 min | Manual detalhado com tudo |
+| **OLLAMA-TOOL-FORCING-QUICK-START.txt** | 5.8 KB | 5 min | Referência visual rápida |
+| **OLLAMA-TOOL-FORCING-TESTS.md** | 4.5 KB | 10 min | 5 exemplos práticos de teste |
+| **OLLAMA-TOOL-FORCING-IMPLEMENTATION.md** | 7.1 KB | 15 min | Documentação técnica avançada |
+| **README.txt** | 10 KB | 10 min | Resumo visual completo |
+
+---
+
+## 📊 Estatísticas
+
+- **Total de arquivos**: 7
+- **Tamanho total**: ~44 KB
+- **Linhas de código/documentação**: ~1,082
+- **Extensão principal**: 91 linhas de TypeScript
+- **Documentação total**: 900+ linhas
+
+---
+
+## 🗺️ GUIA DE NAVEGAÇÃO
+
+### Se você quer COMEÇAR AGORA (2 minutos)
+```
+1. Leia: 00-COMECE-AQUI.txt
+2. Execute: /reload (no ASM Agent)
+3. Teste: "Crie test.txt com 'Olá!' e verifique com bash"
+```
+
+### Se você quer ENTENDER O PROBLEMA (25 minutos)
+```
+Leia nesta ordem:
+1. 00-COMECE-AQUI.txt (visão geral)
+2. OLLAMA-TOOL-FORCING.md (manual completo)
+3. README.txt (diagrama visual)
+```
+
+### Se você quer TESTAR AGORA (10 minutos)
+```
+1. Abra: OLLAMA-TOOL-FORCING-TESTS.md
+2. Copie um dos 5 exemplos
+3. Cole no ASM Agent com seu Qwen/Llama
+4. Observe o modelo chamar ferramentas
+```
+
+### Se você quer CUSTOMIZAR (15 minutos)
+```
+1. Leia: OLLAMA-TOOL-FORCING-IMPLEMENTATION.md
+2. Edite: ollama-tool-forcing.ts
+3. Execute: /reload
+4. Teste mudanças
+```
+
+### Se você quer TROUBLESHOOTING (varia)
+```
+1. Leia: OLLAMA-TOOL-FORCING.md (seção de Troubleshooting)
+2. Verifique: /ollama-tools-info
+3. Se problema persiste: IMPLEMENTATION.md
+```
+
+---
+
+## 📖 Descrição Detalhada de Cada Arquivo
+
+### 1. `00-COMECE-AQUI.txt` ⭐ PRIORITÁRIO
+**Tamanho**: 8.7 KB | **Leitura**: 2 min
+
+Seu ponto de entrada. Contém:
+- Guia de primeiros passos (3 cenários)
+- Como funciona visualmente
+- Dicas quick win
+- Verificação rápida
+- Próximas ações em checklist
+
+**Quando ler**: AGORA! Antes de tudo.
+
+---
+
+### 2. `ollama-tool-forcing.ts` ⭐ PRINCIPAL
+**Tamanho**: 3.2 KB | **Tipo**: TypeScript
+
+A extensão real que funciona. Contém:
+- Importações do ASM Agent ExtensionAPI
+- Comando `/ollama-tools-info` registrado
+- Hook `before_agent_start` implementado
+- Lógica de injeção de regra no system prompt
+- Comentários explicativos
+
+**Quando ler**: Se quiser entender a implementação ou customizar.
+
+**Quando usar**: Automaticamente (auto-descoberta em ~/.asm-agent/extensions/)
+
+---
+
+### 3. `OLLAMA-TOOL-FORCING.md`
+**Tamanho**: 4.4 KB | **Leitura**: 25 min
+
+Manual completo e detalhado. Contém:
+- Explicação do problema (cenário real)
+- Por que modelos menores congelam
+- Como a extensão resolve
+- Quando usar e quando não usar
+- Dicas de otimização (Qwen Coder, Ollama update)
+- Troubleshooting (tabela de problemas/soluções)
+- Remoção da extensão
+
+**Quando ler**: Quando tiver tempo para entender profundamente.
+
+---
+
+### 4. `OLLAMA-TOOL-FORCING-QUICK-START.txt`
+**Tamanho**: 5.8 KB | **Leitura**: 5 min
+
+Referência visual rápida. Contém:
+- O que faz (com caixas visuais)
+- Como usar (3 passos)
+- Regra injetada
+- Documentação complementar
+- Resumo técnico
+- Checklist de implementação
+
+**Quando ler**: Quando precisa de uma visão geral rápida.
+
+---
+
+### 5. `OLLAMA-TOOL-FORCING-TESTS.md`
+**Tamanho**: 4.5 KB | **Leitura**: 10 min
+
+5 testes práticos. Contém:
+- Teste 1: Tarefa Simples
+- Teste 2: Script Python
+- Teste 3: Navegação de Projeto
+- Teste 4: Édição Múltipla
+- Teste 5: Loop Autônomo Completo
+- Como verificar se funciona (sinais ✅/❌)
+- Ajustes se não funcionar
+- Dicas de debug
+
+**Quando usar**: Depois de ativar a extensão, teste cada exemplo.
+
+---
+
+### 6. `OLLAMA-TOOL-FORCING-IMPLEMENTATION.md`
+**Tamanho**: 7.1 KB | **Leitura**: 15 min
+
+Documentação técnica avançada. Contém:
+- Objetivo da custom rule
+- Estrutura de arquivos criados
+- Como funciona internamente (fluxo detalhado)
+- Regra injetada (completa)
+- Personalização (edições, variantes)
+- Casos de uso específicos
+- Segurança e auditorias
+- Aprendizados técnicos
+- Benchmarks esperados
+- Troubleshooting técnico
+
+**Quando ler**: Se quer entender profundamente ou customizar avançadamente.
+
+---
+
+### 7. `README.txt`
+**Tamanho**: 10 KB | **Leitura**: 10 min
+
+Resumo visual completo. Contém:
+- Diagrama visual do problema/solução
+- Checklist de implementação
+- Regra injetada (formatada)
+- Teste agora (quick test)
+- Documentação (tabela de referência)
+- Personalização (todos os casos)
+- Resumo técnico (características)
+- Próximas ações numeradas
+- FAQ rápido
+- Suporte (onde procurar)
+
+**Quando ler**: Para ver tudo visualmente em uma única tela.
+
+---
+
+## 🎯 QUICK REFERENCE (Copie e Cole)
+
+### Comando para verificar status
+```bash
+# No ASM Agent:
+/ollama-tools-info
+```
+
+### Comando para recarregar (após editar extensão)
+```bash
+# No ASM Agent:
+/reload
+```
+
+### Comando para testar (copie para ASM Agent)
+```
+Crie um arquivo test.txt com conteúdo "Olá Ollama!" e use bash para 
+verificar que foi criado corretamente, mostrando seu conteúdo.
+```
+
+### Editar a extensão
+```bash
+nano ~/.asm-agent/extensions/ollama-tool-forcing.ts
+# Edite a seção: const toolForceRule = ...
+# Salve (Ctrl+X, Y, Enter)
+# No ASM Agent: /reload
+```
+
+### Remover extensão
+```bash
+rm ~/.asm-agent/extensions/ollama-tool-forcing.ts
+# No ASM Agent: /reload
+```
+
+---
+
+## 📞 Suporte Rápido
+
+| Problema | Arquivo | Seção |
+|----------|---------|-------|
+| "Não entendi nada" | 00-COMECE-AQUI.txt | Inteira |
+| "Como ativar?" | 00-COMECE-AQUI.txt | COMECE A USAR AGORA |
+| "Não funcionou" | OLLAMA-TOOL-FORCING.md | Troubleshooting |
+| "Quero testar" | OLLAMA-TOOL-FORCING-TESTS.md | Inteira |
+| "Quer customizar?" | IMPLEMENTATION.md | Personalização |
+| "Vi um erro" | IMPLEMENTATION.md | Troubleshooting |
+
+---
+
+## ✨ RESUMO
+
+```
+Local:        ~/.asm-agent/extensions/
+Arquivos:     7 arquivos (44 KB total)
+Ativação:     Automática (próxima sessão)
+Status:       ✅ PRONTO PARA USAR
+```
+
+**Próximo passo**: Abra `00-COMECE-AQUI.txt` agora!
+
+---
+
+*Gerado para Ollama Tool-Forcing Extension v1.0*