Otta Agent — extensão independente para VS Code

Assistente de desenvolvimento com interface de chat inspirada nos fluxos do GitHub Copilot, com identidade Otta própria. Usa preferencialmente os modelos locais llama.cpp e Strata, mas também pode conectar APIs remotas compatíveis com OpenAI. Não depende de GitHub Copilot ou Ollama e não precisa de bibliotecas Node externas.

Funcionalidades da versão 0.1.1

• Painel com aparência integrada ao tema do VS Code, seletor de conexões locais e remotas e seletor de modelos sem editar configurações JSON.
• Perfil padrão local (llama.cpp em 8080 e Strata em 8095), mais predefinições remotas para OpenAI, Mistral e OpenRouter; conexão customizada aceita outros serviços OpenAI-compatíveis.
• Botões Chat e Agent. Chat não disponibiliza ferramentas de escrita/terminal; Agent mantém leitura, edição, terminal e ciclo de ferramentas com autorização.
• Ícone de engrenagem abre, dentro do próprio chat, formulário de endpoint, backend, tipo de autenticação, ID do modelo, temperatura, reasoning, contexto e timeout.
• Credenciais via VS Code SecretStorage (recurso seguro da plataforma), fora do settings.json: chave de API Bearer ou usuário/senha HTTP Basic. Nenhuma credencial é enviada de volta ao painel após salvar; ele mostra apenas se há credencial configurada. Chaves/senhas nunca são adicionadas ao repositório da extensão. Os dados são enviados apenas ao endpoint escolhido durante solicitações autenticadas. Serviços com OAuth/login em navegador requerem integração dedicada.
• Conexões remotas exigem HTTPS, exceto serviços no computador local. Mensagens, contexto de código e resultados de ferramentas enviados para provedores remotos passam pela infraestrutura do provedor.
• ↑ na caixa de mensagem recupera a última solicitação enviada, incluindo múltiplas mensagens anteriores. ↓ retorna no histórico e ao rascunho original. Ctrl+Enter envia.
• Autoaprovações de ferramentas permanecem explícitas e são independentes para cada conexão remota, sem herdar aprovações anteriores de modelos locais.

Configuração rápida no painel

1. Abra a barra lateral Otta Agent no VS Code.
2. No primeiro menu, escolha llama.cpp ou Strata (prioridade local). Se quiser, clique em ⚙ → Nova conexão para cadastrar uma API remota.
3. Para a API remota, escolha Chave de API (Bearer) ou Usuário e senha (Basic) conforme o serviço, preencha os campos secretos e clique Salvar conexão. Em geral, OpenAI/Mistral/OpenRouter usam uma chave de API; usuário e senha não substituem o login web/OAuth desses serviços.
4. Clique no ícone ↻ ao lado do modelo para consultar os modelos disponíveis ou digite seu ID em ⚙ → ID do modelo e salve.
5. Escolha Agent para alterar arquivos com ferramentas ou Chat para conversar sem ferramentas; configure reasoning, temperatura e contexto clicando em ⚙.
6. Teste a conexão no ↻ do cabeçalho. Solicitações Agent exigem uma pasta de projeto aberta e confiável.

As credenciais de versões antigas adicionadas manualmente em llamaAgent.apiKey não são migradas automaticamente. Digite-as uma vez no novo painel para guardar de forma protegida. O restante das configurações antigas do VS Code fica disponível como configuração avançada/legada.

Funcionalidades

• Painel próprio na barra lateral do VS Code.
• Ciclo de ferramentas sem limite de etapas nem teto de tokens de saída imposto pela extensão, até o agente retornar uma resposta final ou ser interrompido.
• Gerenciamento automático do contexto: em llama.cpp lê /props; em Strata identifica o serviço em /health e usa max_context (com fallback para /props e /v1/models[].meta.n_ctx). Reserva espaço, resume mensagens antigas e tenta recuperar erros de contexto e finish_reason: length. A contagem exata via /input_tokens é exclusiva do llama.cpp; no Strata é feita uma estimativa conservadora.
• Suporte a Strata e família Gyro/Qwen3.8-Flash-Next: endpoints compatíveis com OpenAI, streaming, funções nativas, reasoning_effort configurável e diagnóstico de nomes de ferramentas rejeitados pelo servidor.
• Monitor de geração Strata no próprio painel: consulta /metrics aproximadamente a cada 1,5 segundo enquanto o agente trabalha; mostra tokens/s, tokens gerados, tempo total, uso de GPU e VRAM, progresso de leitura do prompt e, quando o servidor encerra a etapa, tempo do prompt. O monitor não interfere nas requisições do agente e é desativado no backend llama.cpp.
• Perfil GPT-OSS 20B automático: tool calls nativos do llama.cpp com execução sequencial, reasoning low/medium/high, amostragem recomendada (temperature=1, top_p=1, top_k=0, min_p=0) e nenhum limite artificial de saída da tarefa.
• Modo de execução ativo: quando o pedido é criar, implementar ou modificar um projeto, respostas que só dão orientações não são tratadas como tarefa concluída. Usa tool_choice: auto e cobra uma chamada real de ferramenta se o modelo tentar apenas explicar.
• Recuperação automática de erro peg-native format do llama.cpp: até duas novas tentativas da etapa, sem repetir edições ou comandos já executados. Se o servidor falhar três vezes seguidas, exibe diagnóstico em vez de marcar a tarefa como concluída.
• Em pedidos enormes (ex.: desenvolver a distro Otta OS), pede para criar um primeiro incremento verificável no workspace em vez de declarar a tarefa impossível. Mantém a necessidade de aprovação de escrita/comandos e nunca autoriza instalação ou particionamento de discos por conta própria.
• Compatibilidade preservada com Ornith e outros GGUFs: o perfil específico só é ativado para modelos identificados como gpt-oss ou por escolha do usuário.
• Compactação em blocos completos: cada chamada de ferramenta permanece vinculada ao seu resultado, incluindo quando você interrompe a execução.
• Leitura de arquivos com números de linha.
• Pesquisa de texto e listagem de arquivos do projeto.
• Edição pontual (replace_in_file) e criação/substituição (write_file), com aprovação por ação ou autoaprovação opcional.
• Comandos locais (run_command), com aprovação por ação ou autoaprovação opcional, saída e código de retorno.
• Comandos em PowerShell no Windows (sem necessidade de abrir um shell externo), sh no Linux/macOS.
• Restrição de arquivos à primeira pasta aberta no workspace e proteção contra links simbólicos para fora dela.
• Bloqueio de acesso automático a .env, .pem, .key e nomes comuns de arquivos de credenciais.
• Interrupção de solicitações, timeout e diagnóstico de limite de saída.
• Streaming HTTP de geração com reconstituição de tool_calls completos, incluindo reasoning.
• Autoaprovação opcional, separada para edições e comandos e persistente apenas no workspace atual.
• Conversa contínua por sessão, mas não persistida entre reinicializações do VS Code.

Instalação no Windows 11

1. Baixe llama-agent-local-0.1.1.vsix.
2. No VS Code, pressione Ctrl+Shift+P e selecione Extensions: Install from VSIX....
3. Escolha o arquivo .vsix e recarregue a janela se solicitado.
4. Abra um projeto como pasta no VS Code.
5. Clique no ícone Otta Agent na barra lateral.

Alternativa PowerShell: code --install-extension "C:\caminho\llama-agent-local-0.1.1.vsix" --force.

Autoaprovação de ações

No painel Llama Agent, acima da caixa de mensagem, há duas opções:

• Autoaprovar edições: permite replace_in_file e write_file sem diálogo por alteração. Arquivos sensíveis, caminhos fora do workspace e workspaces não confiáveis continuam bloqueados.
• Autoaprovar comandos: permite run_command sem diálogo por comando. Atenção: comandos PowerShell/shell podem acessar ou modificar arquivos fora do projeto e executar ações destrutivas com as permissões do processo do VS Code.

Cada opção começa desativada e requer uma confirmação explícita na primeira ativação. O estado permanece salvo por workspace, sem modificar os arquivos do projeto. Pode ser desativado novamente no painel antes da próxima execução. Durante uma execução, use Parar se precisar interromper o agente.

Usar com Strata (porta 8095)

No PowerShell como Administrador, inicie o modelo conforme a configuração que você já testou (a pasta E:\Strata\Modelos recebe os arquivos do modelo):

strata launch --family gyro --model Gyro-S --context 32k --parallel 1 --vision off --data-dir "E:\Strata\Modelos" --access local --port 8095 --no-api-key

Atenção: --plan apenas descreve o download, sem instalar nem iniciar o servidor. Remova --plan como no exemplo acima e espere o modelo carregar. O Gyro-S demanda um download grande e recursos de memória significativos.

No VS Code, abra o painel Otta Agent, selecione Strata no seletor de conexões e confirme a porta 8095 na engrenagem. As opções avançadas antigas do VS Code correspondem a:

Clique Testar conexão no painel. Deve aparecer o modelo e o contexto real; por exemplo 32.768 tokens para --context 32k. O modo Agent depende de tool calls estruturados devolvidos pelo Strata; a extensão envia seis ferramentas e processa suas respostas. Quando o servidor devolver uma ferramenta não declarada (por exemplo bash), a extensão orienta o modelo a usar run_command ou outra ferramenta válida. O servidor Strata continua responsável pela compatibilidade do modelo com chamadas de ferramenta.

Durante a execução, aparece o quadro STRATA · DESEMPENHO acima do status do agente. Ele traz valores de /metrics.live enquanto gera; após a etapa, troca para os dados da última requisição (/metrics.requests[0]). O tempo do prompt só aparece após a conclusão da etapa, pois não é preciso inventar uma duração enquanto o prompt ainda está sendo processado. Se /metrics não estiver acessível, a execução do agente continua normalmente.

O Strata aceita /v1/chat/completions; não é necessário llama serve, --jinja nem --agent ao usar Strata. Não execute os dois servidores na mesma porta. Se trocar de backend/modelo na configuração, a extensão inicia um histórico de conversa novo na próxima mensagem.

Iniciar o llama.cpp

Exemplo recomendado para a RTX 4080 SUPER com GPT-OSS 20B MXFP4 no disco E:

llama serve -m "E:\Modelos\gpt-oss-20b\gpt-oss-20b-MXFP4.gguf" -ngl 99 -c 98304 -np 1 -fa on --cache-type-k q4_0 --cache-type-v q4_0 --jinja --cache-reuse 256 --host 127.0.0.1 --port 8080

O arquivo deverá existir nesse caminho. A extensão funciona com o servidor llama.cpp pela API OpenAI-compatible; --agent do servidor não é necessário para executar as seis ferramentas da extensão. Para GPT-OSS, --jinja e o template do modelo são essenciais. Configure o endpoint da extensão como http://127.0.0.1:8080 e o modelo como auto.

Exemplo alternativo para Qwen3-Coder já disponível:

llama serve -m "C:\Modelos\Qwen3-Coder-30B-A3B-Instruct-Q3_K_M\qwen3-coder-30b-a3b-instruct-q3_k_m.gguf" --jinja --agent -ngl 99 -c 65536 -np 1 -fa on --cache-type-k q4_0 --cache-type-v q4_0 --host 127.0.0.1 --port 8080

Observação: flags e o formato do template dependem da versão do llama.cpp. Se o modelo não oferecer function calling de forma estruturada, a extensão mostrará o erro em vez de fingir que executou ferramentas. Para versões antigas, --jinja é obrigatório no servidor para ferramentas.

As flags -c 65536 e cache KV Q4 podem consumir mais VRAM do que o disponível conforme o modelo e o contexto real. Ajuste conforme nvidia-smi.

Configurar o servidor

As preferências principais são alteradas diretamente no painel do Otta Agent. O VS Code também tem as seguintes configurações avançadas/legadas:

Testes sugeridos

1. Liste os arquivos principais deste projeto, sem modificar nada.
2. Leia o README e identifique a linguagem e os comandos de teste.
3. Crie agent-test.md com a descrição do projeto e confira que foi criado corretamente.
4. Em uma pasta vazia de teste: Crie um projeto inicial para a distro Otta OS baseada em Arch Linux. Implemente os arquivos reais do projeto e valide o que for possível sem instalar nada no computador.

Você verá um pedido de autorização antes do terceiro teste. Faça-o em um repositório de teste ou aceite somente alterações que deseje manter.

No quarto teste, o GPT-OSS deve começar chamando uma ferramenta e criar arquivos dentro do workspace. Uma resposta apenas explicativa provoca outra tentativa de ação em vez de ser marcada como Concluído.. A extensão não instala, formata nem substitui o sistema operacional do computador automaticamente; os artefatos são arquivos de projeto.

Limitações conhecidas

• Versão inicial/experimental, fornecida como projeto local. Não é publicada no Marketplace.
• Apenas a primeira pasta do workspace é usada como raiz.
• O workspace deve estar disponível como sistema de arquivos local (file:).
• Sem suporte integrado a MCP, imagens, subagentes ou checkpoint nesta versão.
• A compactação automática preserva um resumo, mas pode perder detalhes de etapas antigas. A requisição atual do usuário é mantida. Se ela sozinha exceder o contexto, será necessário reduzi-la ou aumentar -c.
• Ao compactar, uma chamada interna de resumo usa até 1200 tokens de saída; isso não limita a geração de respostas e ferramentas do agente.
• No GPT-OSS, o resumo interno usa reasoning low para economizar tempo; a tarefa principal usa o nível configurado (padrão medium).
• A detecção de pedidos de implementação usa palavras-chave em português/inglês mais comuns; não é perfeita. Uma solicitação formulada como pergunta pode ser interpretada como consulta teórica. Prefira verbos diretos (Crie, Implemente, Corrija) ao pedir alterações.
• O tratamento GPT-OSS é testado com fluxos HTTP simulados. É necessário validar o template e o servidor llama.cpp no Windows com o arquivo GGUF real, pois builds antigos podem ter diferenças de suporte.
• Alguns builds do llama.cpp produzem HTTP 500 com The model produced output that does not match the expected peg-native format quando o GPT-OSS gera um cabeçalho Harmony inesperado. A extensão tenta recuperar a etapa automaticamente, mas atualizar o llama.cpp é recomendado caso o problema seja frequente.
• Quando /v1/chat/completions/input_tokens não estiver disponível na versão do llama.cpp, a extensão usa uma estimativa conservadora e ainda tenta se recuperar de erros de limite.
• No Strata, a extensão não consulta /v1/chat/completions/input_tokens, usando a estimativa conservadora de tokens. Ela respeita o contexto anunciado pelo servidor, que pode ser menor que a janela máxima teórica do modelo.
• O Strata pode responder com ferramentas não declaradas ou somente texto. A extensão tenta orientar a escolha da ferramenta e não afirma ter modificado arquivos quando a ferramenta não foi executada. O servidor e o modelo precisam oferecer tool calling válido.
• O modo agente depende de um GGUF compatível com tool calling e do template correto no llama.cpp.
• Utiliza stream: true para manter a conexão ativa em gerações longas, agrega o fluxo e só executa ferramentas quando a chamada completa é recebida. O status mostra caracteres recebidos; o texto final aparece quando a etapa termina.
• As edições e os comandos são executados localmente. Revise sempre as autorizações; não habilite execução automática de comandos de modelos não confiáveis.
• Comandos encerrados por timeout podem deixar subprocessos ativos dependendo do shell/Windows; verifique o Gerenciador de Tarefas em caso de interrupção de builds complexos.

Se ocorrer fetch failed

1. Verifique curl.exe -i http://127.0.0.1:8080/health (llama.cpp) ou curl.exe -i http://127.0.0.1:8095/health (Strata) no PowerShell.
2. Confira o terminal em que llama serve está rodando (especialmente erros de CUDA/VRAM).
3. Configure llamaAgent.endpoint com a porta do servidor ativo: 8080 para llama.cpp ou 8095 para o Strata do exemplo.
4. Para raciocínio demorado, as versões 0.1.1+ recebem respostas por streaming e mostram um diagnóstico mais específico quando o servidor fecha a conexão.
5. A extensão não envia max_tokens; por padrão o llama.cpp não impõe teto de geração (n_predict: -1), mas cada geração ainda precisa caber no contexto (-c) disponível. Se o servidor devolver finish_reason: length, pode haver esgotamento do contexto ou outro limite definido no servidor.
6. Não há limite de etapas de ferramentas. Uma tarefa pode continuar até ser concluída ou você clicar em Parar. Na versão 0.1.5, o agente compacta o histórico quando se aproxima do limite de contexto e tenta novamente uma geração interrompida por falta de espaço. Se o pedido atual for grande demais, aparecerá um erro explicativo.

Código-fonte

O próprio arquivo .vsix contém todos os arquivos-fonte JavaScript, o HTML, os testes e esta documentação. É um pacote ZIP padrão; pode ser aberto com 7-Zip para inspeção.

Licença MIT.