Ferramentas de agente integradas

Estas são as ferramentas ligadas ao servidor que o runtime de agente integrado regista diretamente — servidor de linguagem, pesquisa estrutural, depurador, kernels, perguntas e controlo de workers — por oposição às ferramentas MCP que interliga e às ferramentas genéricas de ficheiros, pesquisa e shell do runtime do harness. Não estão no registo MCP: um cliente MCP externo não as verá, porque cada uma está ligada a um recurso vivo do lado do servidor — um processo de servidor de linguagem, um adaptador de depuração, um interpretador — que pertence a uma execução.

Cada ferramenta aqui só é registada quando o recurso que a sustenta está ligado para a execução — um supervisor de servidor de linguagem ou de depuração, um analisador tree-sitter, uma fábrica de kernels, uma porta de perguntas, um conjunto de workers do vibe. A deteção de um servidor de linguagem ou de um adaptador de depuração para este checkout é uma verificação separada e posterior (status / adapters): essas ferramentas mantêm-se na superfície para que o agente possa perguntar porque é que nada é utilizável, em vez de adivinhar.

Níveis de aprovação

Cada ferramenta declara um nível, e o nível decide que superfícies a veem — não apenas se emite um pedido de aprovação. O modo de plano e os subagentes só de leitura estão limitados a read, pelo que uma ferramenta de nível write ou exec está totalmente ausente do respetivo esquema.

Nível	Significado	Ferramentas aqui
read	Sem efeitos secundários	lsp, ast_grep, ask_user, as cinco vibe_*
write	Altera ficheiros	lsp_rename, ast_edit, resolve
exec	Inicia ou controla um processo	debug, eval

---

lsp — consultas ao servidor de linguagem

Registada quando a execução tem um supervisor de servidor de linguagem e um diretório de trabalho. Se um servidor consegue mesmo responder é detetado no momento da chamada, como uma interseção: tem de existir um marcador de raiz e o binário do servidor tem de resolver. Qualquer um deles sozinho significa que nenhum servidor arranca — o status di-lo — em vez de uma suposição silenciosa.

As posições são indicadas por line mais uma subcadeia symbol, nunca por coluna. Um modelo a quem se pede uma coluna adivinha, e uma suposição errada resolve para um símbolo diferente na mesma linha — uma resposta que parece certa e é sobre outra coisa. Omitir symbol numa ação de navegação é um erro, não uma suposição da primeira coluna.

Ação	Argumentos	Devolve
diagnostics	file (ou "*")	Erros e avisos; "*" executa o verificador do projeto em vez disso
definition	file, line, symbol	Onde o símbolo é declarado
type_definition	file, line, symbol	Onde o seu tipo é declarado
implementation	file, line, symbol	Implementações concretas
references	file, line, symbol	Cada utilização, limitada a 50
hover	file, line, symbol	Assinatura e comentário de documentação
symbols	query ou file	Pesquisa no espaço de trabalho com query (limitada a 100); símbolos do documento com file (limitados a 200)
code_actions	file, line, symbol	Correções rápidas que o servidor oferece
status	—	Que servidores estão a correr, e para que raízes
reload	—	Reinicia o servidor para esta raiz

Diagnósticos ao escrever

O ganho não está na ferramenta. write, edit e apply_patch estão envolvidas: depois da escrita, o ficheiro é sincronizado e guardado através do servidor de linguagem, e apenas os diagnósticos introduzidos recentemente são incorporados no resultado da ferramenta. Um agente fica a saber que quebrou a build no momento em que a quebrou, sem ter de se lembrar de perguntar.

Os diagnósticos já reportados são suprimidos por um registo por execução indexado por gravidade, código e mensagem — com a posição deliberadamente excluída, para que um diagnóstico que apenas desceu quatro linhas não volte a ser reportado como novo.

lsp_rename — renomear em todo o projeto

Uma ferramenta separada, de nível write, por um motivo exato: é o nível que decide a visibilidade. Incluir a renomeação no lsp daria a um explorador só de leitura a capacidade de reescrever o repo, ou colocaria cada hover atrás de um pedido de aprovação.

Argumento	Significado
file	Onde está o símbolo
line	Linha com índice 1
symbol	Subcadeia que o identifica nessa linha
new_name	Como o chamar

---

ast_grep — pesquisa estrutural

Encontra código pela forma em vez de pelo texto. O $NAME corresponde a qualquer nó, o $$$NAME corresponde a uma sequência de irmãos, e o $_ é um curinga que não vincula nada.

A propriedade que o torna um comparador e não uma expressão regular com passos extra: uma metavariável repetida num padrão tem de capturar o mesmo texto.

ast_grep(pattern: "if ($X != null) $X.dispose()", language: "dart")

corresponde a uma guarda que descarta aquilo que testou, e não corresponde a uma que descarta outra coisa.

Argumento	Significado
pattern	Um fragmento de código com metavariáveis
path	Ficheiro ou diretório a pesquisar; por omissão, todo o espaço de trabalho
language	Um id de gramática incluído (dart, python, rust, c, …). Inferido quando path indica um ficheiro
max_results	Por omissão 50

O padrão é analisado pela mesma gramática do ficheiro

Assim, dispose(x) corresponde à chamada independentemente do espaçamento, das quebras de linha ou dos comentários — e nunca corresponde aos mesmos caracteres dentro de um literal de string ou de um comentário.

Um fragmento é analisado num andaime, não isolado

dispose(x) analisado no nível superior do Dart é uma assinatura de função válida. O compilador de padrões tenta uma escada de contextos (instrução, expressão, membro de classe, declaração) e usa o primeiro que aceita o fragmento. Um padrão que nenhum contexto aceita é reportado como não analisável em vez de ser procurado e silenciosamente não encontrado.

ast_edit — reescrita estrutural, preparada

A mesma correspondência, mais um modelo rewrite com as metavariáveis substituídas de volta. Nada é escrito. A alteração é preparada e o resultado indica um edit_id.

ast_edit(pattern: "dispose($X)", rewrite: "$X.dispose()", language: "dart")
→ (proposed) 12 replacements in 4 files … call resolve with edit_id "edit_1"

Argumento	Significado
pattern	O que corresponder
rewrite	O que colocar lá, com $NAME substituído
path	Âmbito; por omissão, todo o espaço de trabalho
language	Id da linguagem

resolve — confirmar ou descartar uma alteração preparada

Argumento	Significado
edit_id	Do resultado (proposed)
action	accept ou discard

Cada ficheiro é comparado com o conteúdo capturado no momento da preparação, e qualquer divergência recusa a alteração inteira. Uma reescrita estrutural aplicada em parte deixa uma árvore que não compila nem na forma antiga nem na nova.

---

debug — conduzir um depurador

Registada quando a execução tem um supervisor de sessão de depuração, um diretório de trabalho e um id de conversa. Se um adaptador consegue mesmo arrancar é detetado no momento da chamada, pela mesma regra de interseção do servidor de linguagem (marcador de raiz e binário). Nível exec; não é seguro em paralelo (uma sessão é estado entre chamadas, pelo que um continue a ultrapassar um stack leria um frame que já se moveu).

Uma sessão por conversa, com um TTL rígido (30 minutos). Um segundo launch é recusado em vez de substituir silenciosamente o primeiro.

Op	Argumentos	Notas
adapters	—	Que adaptadores são utilizáveis aqui, e porque não
status	—	Se há uma sessão a correr, e onde parou
breakpoints	file, lines[]	Um lines vazio limpa o ficheiro. Podem ser definidos antes de iniciar
launch	program, args[]	Inicia o programa parado nos seus pontos de interrupção
attach	port	Liga-se a um programa em depuração já a correr
continue	thread_id?	Executa até à paragem seguinte
pause	thread_id?	Pára-o onde está
step_over / step_in / step_out	thread_id?	Avança um passo
threads	—	Ids e nomes das threads
stack	thread_id?	Frames, limitados a 30
scopes	frame_id	Âmbitos de um frame, cada um com uma reference
variables	reference	Filhos, limitados a 50; valores limitados a 400 caracteres
evaluate	expression, frame_id?	Avaliada no próprio âmbito do frame
output	—	O stdout/stderr do programa em depuração, limitado
terminate	—	Termina a sessão e mata o adaptador

Adaptadores

Id	Comando	Marcadores de raiz
dart	dart debug_adapter	pubspec.yaml
debugpy	python3 -m debugpy.adapter	pyproject.toml, setup.py, requirements.txt
lldb	lldb-dap	Cargo.toml, CMakeLists.txt
delve	dlv dap	go.mod

O debugpy prefere um .venv/bin ou venv/bin local do projeto em vez do $PATH: um python do $PATH é um ambiente diferente, e anexar a partir do errado falha de uma forma que se lê como código avariado.

---

eval — interpretadores persistentes

Uma célula Python ou JavaScript cujas variáveis, importações e dados carregados sobrevivem entre chamadas. Nível exec; não é seguro em paralelo.

Argumento	Significado
code	A célula
description	Obrigatório. 5 a 10 palavras para a etiqueta da transcrição
language	python (predefinição) ou javascript
reset	Descarta o interpretador e começa primeiro de forma limpa

• A última expressão é ecoada como num notebook.
• O display() funciona, um DataFrame do pandas é representado como uma tabela, e uma figura do matplotlib volta como uma imagem que a transcrição mostra.
• Os idiomas do IPython que as pessoas escrevem por reflexo — %pip, %cd, !cmd, %%bash, %%timeit — são reescritos como código simples. O %pip também expulsa o sys.modules, para que o próximo import veja o que acabou de ser instalado.

Chamar as suas próprias ferramentas a partir de dentro de uma célula

contents = tool("read", {"path": "lib/auth.dart"})

A ponte volta a entrar no registo de ferramentas do harness, pelo que as barreiras, a aprovação e cada wrapper se aplicam exatamente como numa chamada emitida pelo modelo. Segue o próprio pipe do kernel em vez de um socket de loopback: sem porta, sem segredo, sem regra de egresso.

O tempo limite da célula é um orçamento de inatividade (predefinição de 5 minutos) e é suspenso enquanto há uma chamada através da ponte pendente, para que uma célula que se distribui por subagentes não seja morta a meio da distribuição.

Onde é que o kernel é executado

No recinto da conversa quando esta tem um, no anfitrião caso contrário. Não arranca um recinto para lá chegar — a mesma regra que impede um separador de rig de arrancar automaticamente.

---

ask_user — fazer uma pergunta ao humano

Nível read. A única forma de uma execução perguntar algo ao operador. Apresenta um cartão numerado na conversa e bloqueia até alguém responder, saltar ou a pergunta expirar. Nunca escreva a pergunta como uma mensagem de chat — isso termina o turno.

Argumento	Significado
question	O que perguntar
context	Opcional: porque está a perguntar e o que depende da resposta
options[]	Escolhas, cada uma {label, description?}
allow_free_text	Se uma resposta escrita é aceite
multi_select	Se podem ser escolhidas várias opções

Um salto é um êxito: avance com base numa suposição declarada e não volte a perguntar. Uma expiração do tempo limite é um erro com a mesma instrução. Os pedidos de permissão («posso fazer isto?») são um portão separado e são apresentados no mesmo cartão na conversa.

Só é registada quando existem tanto uma porta de perguntas como um espaço de destino. Sem um humano ligado, a chamada falha em vez de bloquear para sempre — a mesma postura de falha fechada que um prompt de barreira adota quando não há nenhum aprovador ligado.

---

vibe_* — dirigir workers em segundo plano

Só é registada enquanto o modo vibe está ligado. As cinco são de nível read: o portão pertence às ferramentas do worker, onde a edição acontece realmente.

Ferramenta	Argumentos	Notas
vibe_spawn	brief, label, tier?	Devolve imediatamente; o worker continua a correr
vibe_send	worker_id, message	Acrescenta ao briefing e volta a executar
vibe_wait	worker_id, timeout_seconds?	Bloqueia até ele terminar
vibe_kill	worker_id	Pára-o
vibe_list	—	Nível, estado, tempo decorrido e último resultado

O tier é fast (trabalho mecânico com uma especificação clara) ou good (conceção, discernimento ou revisão do resultado de um worker fast).