Instrumente agent integrate

Acestea sunt instrumentele legate de server pe care runtime-ul de agent integrat le înregistrează direct — server de limbaj, căutare structurală, depanator, kerneluri, întrebări și controlul workerilor — spre deosebire de instrumentele MCP pe care le aduce prin punte și de instrumentele generice de fișiere, căutare și shell din runtime-ul harness-ului. Nu se află în registrul MCP: un client MCP extern nu le va vedea, pentru că fiecare este legat de o resursă activă de pe server — un proces de server de limbaj, un adaptor de depanare, un interpretor — care aparține unei singure rulări.

Fiecare instrument de aici este înregistrat doar când resursa din spatele lui este conectată pentru rulare — un supraveghetor de server de limbaj sau de depanare, un analizor sintactic tree-sitter, o fabrică de kerneluri, un port de întrebări, o listă de vibe. Detectarea unui server de limbaj sau a unui adaptor de depanare pentru acest checkout este o verificare separată, ulterioară (status / adapters): instrumentele respective rămân pe suprafață ca agentul să poată întreba de ce nu este utilizabil nimic, în loc să ghicească.

Niveluri de aprobare

Fiecare instrument declară un nivel, iar nivelul decide care suprafețe îl văd — nu doar dacă solicită aprobare. Modul plan și subagenții doar în citire sunt limitați la read, așa că un instrument de nivel write sau exec lipsește complet din schema lor.

Nivel	Semnificație	Instrumente aici
read	Fără efecte secundare	lsp, ast_grep, ask_user, cele cinci vibe_*
write	Modifică fișiere	lsp_rename, ast_edit, resolve
exec	Pornește sau controlează un proces	debug, eval

---

lsp — interogări către serverul de limbaj

Înregistrat când rularea are un supraveghetor de server de limbaj și un director de lucru. Dacă un server poate răspunde cu adevărat se detectează la momentul apelului, ca o intersecție: trebuie să existe un marker de rădăcină și binarul serverului trebuie să se rezolve. Oricare dintre ele singur înseamnă că niciun server nu pornește — status spune asta — în loc să fie o presupunere tăcută.

Pozițiile sunt adresate prin line plus un subșir symbol, niciodată prin coloană. Un model căruia i se cere o coloană ghicește, iar o presupunere greșită se rezolvă la un alt simbol de pe aceeași linie — un răspuns care pare corect, dar este despre altceva. Omiterea lui symbol la o acțiune de navigare este o eroare, nu o presupunere a primei coloane.

Acțiune	Argumente	Returnează
diagnostics	file (sau "*")	Erori și avertismente; "*" rulează în schimb verificatorul de proiect
definition	file, line, symbol	Unde este declarat simbolul
type_definition	file, line, symbol	Unde este declarat tipul lui
implementation	file, line, symbol	Implementările concrete
references	file, line, symbol	Fiecare utilizare, plafonat la 50
hover	file, line, symbol	Semnătura și comentariul de documentație
symbols	query sau file	Căutare în spațiul de lucru cu query (plafonat la 100); simboluri de document cu file (plafonat la 200)
code_actions	file, line, symbol	Corecturile rapide oferite de server
status	—	Ce servere rulează și pentru ce rădăcini
reload	—	Repornește serverul pentru această rădăcină

Diagnostice la scriere

Câștigul nu este instrumentul. write, edit și apply_patch sunt învelite: după scriere, fișierul este sincronizat și salvat prin serverul de limbaj, iar doar diagnosticele introduse recent sunt incluse în rezultatul instrumentului. Un agent află că a stricat build-ul în momentul în care l-a stricat, fără să fie nevoit să-și amintească să întrebe.

Diagnosticele deja raportate sunt suprimate de un registru pe rulare indexat după severitate, cod și mesaj — poziția este exclusă în mod deliberat, astfel încât un diagnostic care s-a mutat doar cu patru linii mai jos să nu fie raportat din nou ca nou.

lsp_rename — redenumire la nivel de proiect

Un instrument separat, de nivel write, pentru exact un motiv: nivelul decide vizibilitatea. Dacă redenumirea ar fi fost inclusă în lsp, fie i s-ar fi dat unui explorator doar în citire capacitatea de a rescrie repo-ul, fie fiecare hover ar sta în spatele unei solicitări de aprobare.

Argument	Semnificație
file	Unde se află simbolul
line	Linie indexată de la 1
symbol	Subșir care îl identifică pe acea linie
new_name	Cum să fie numit

---

ast_grep — căutare structurală

Găsește cod după formă, nu după text. $NAME potrivește orice nod, $$$NAME potrivește o serie de noduri frați, iar $_ este un wildcard care nu leagă nimic.

Proprietatea care îl face un potrivitor și nu o expresie regulată cu pași în plus: o metavariabilă repetată într-un singur șablon trebuie să capteze același text.

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

potrivește o gardă care eliberează exact ce a testat și nu potrivește una care eliberează altceva.

Argument	Semnificație
pattern	Un fragment de cod cu metavariabile
path	Fișierul sau directorul de căutat; implicit întregul spațiu de lucru
language	Un id de gramatică livrat (dart, python, rust, c, …). Dedus când path indică un fișier
max_results	Implicit 50

Șablonul este analizat de aceeași gramatică precum fișierul

Astfel, dispose(x) potrivește apelul indiferent cum este spațiat, încadrat sau comentat — și nu potrivește niciodată aceleași caractere dintr-un literal de șir sau dintr-un comentariu.

Un fragment este analizat într-un schelet, nu în gol

dispose(x) analizat la nivelul superior al Dart este o semnătură de funcție validă. Compilatorul de șabloane încearcă o scară de contexte (instrucțiune, expresie, membru de clasă, declarație) și îl folosește pe primul care acceptă fragmentul. Un șablon pe care niciun context nu îl acceptă este raportat ca neanalizabil sintactic, în loc să fie căutat și să nu fie găsit în tăcere.

ast_edit — rescriere structurală, etapizată

Aceeași potrivire, plus un șablon rewrite în care metavariabilele sunt substituite la loc. Nu se scrie nimic. Modificarea este etapizată, iar rezultatul numește un 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"

Argument	Semnificație
pattern	Ce să potrivească
rewrite	Ce să pună acolo, cu $NAME substituit
path	Domeniul; implicit întregul spațiu de lucru
language	Id-ul limbajului

resolve — aplică sau renunță la o modificare etapizată

Argument	Semnificație
edit_id	Din rezultatul (proposed)
action	accept sau discard

Fiecare fișier este comparat cu conținutul capturat în momentul etapizării, iar orice nepotrivire refuză întreaga modificare. O rescriere structurală aplicată parțial lasă un arbore care nu se compilează nici cu forma veche, nici cu cea nouă.

---

debug — condu un depanator

Înregistrat când rularea are un supraveghetor de sesiuni de depanare, un director de lucru și un id de conversație. Dacă un adaptor poate porni cu adevărat se detectează la momentul apelului, după aceeași regulă de intersecție ca la serverul de limbaj (marker de rădăcină și binar). Nivel exec; nu este sigur la rulare în paralel (o sesiune este stare între apeluri, așa că un continue care depășește un stack ar citi un cadru care s-a mișcat deja).

O singură sesiune per conversație, cu un TTL strict (30 de minute). Un al doilea launch este refuzat în loc să îl înlocuiască în tăcere pe primul.

Op	Argumente	Note
adapters	—	Ce adaptoare sunt utilizabile aici și de ce nu
status	—	Dacă rulează o sesiune și unde s-a oprit
breakpoints	file, lines[]	lines gol șterge fișierul. Pot fi stabilite înainte de lansare
launch	program, args[]	Pornește programul oprit la punctele tale de întrerupere
attach	port	Se conectează la un proces depanat care rulează deja
continue	thread_id?	Rulează până la următoarea oprire
pause	thread_id?	Îl oprește acolo unde se află
step_over / step_in / step_out	thread_id?	Avansează cu un pas
threads	—	Id-urile și numele firelor de execuție
stack	thread_id?	Cadre, plafonate la 30
scopes	frame_id	Scopuri pe un cadru, fiecare cu o reference
variables	reference	Copii, plafonate la 50, valori plafonate la 400 de caractere
evaluate	expression, frame_id?	Evaluat în scopul propriu al cadrului
output	—	stdout/stderr-ul procesului depanat, mărginit
terminate	—	Încheie sesiunea și omoară adaptorul

Adaptoare

Id	Comandă	Markere de rădăcină
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

debugpy preferă un .venv/bin sau venv/bin local proiectului în locul lui $PATH: un python din $PATH este un mediu diferit, iar atașarea din cel greșit eșuează într-un mod care se citește ca un cod stricat.

---

eval — interpretoare persistente

O celulă Python sau JavaScript ale cărei variabile, importuri și date încărcate supraviețuiesc între apeluri. Nivel exec; nu este sigur la rulare în paralel.

Argument	Semnificație
code	Celula
description	Obligatoriu. 5–10 cuvinte pentru eticheta din transcriere
language	python (implicit) sau javascript
reset	Elimină interpretorul și pornește curat de la început

• Ultima expresie este afișată așa cum face un notebook.
• display() funcționează, un DataFrame pandas se randează ca tabel, iar o figură matplotlib revine ca o imagine pe care transcrierea o afișează.
• Idiomurile IPython pe care lumea le tastează reflex — %pip, %cd, !cmd, %%bash, %%timeit — sunt rescrise în cod simplu. %pip elimină și intrările din sys.modules, așa că următorul import vede ce tocmai a fost instalat.

Apelarea propriilor instrumente din interiorul unei celule

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

Puntea reintră în registrul de instrumente al harness-ului, așa că guardrail-urile, aprobarea și fiecare înveliș se aplică exact ca la un apel emis de model. Călătorește pe conducta proprie a kernelului, nu pe un socket loopback: fără port, fără secret, fără regulă de ieșire în rețea.

Timeout-ul celulei este un buget de inactivitate (implicit 5 minute) și este suspendat cât timp un apel prin punte este în curs, așa că o celulă care face fan-out către subagenți nu este omorâtă la mijlocul fan-out-ului.

Unde rulează kernelul

În mediul izolat al conversației când aceasta are unul, altfel pe gazdă. Nu pornește un mediu izolat ca să ajungă acolo — aceeași regulă care împiedică pornirea automată a unui tab de stație.

---

ask_user — pune o întrebare omului

Nivel read. Singurul mod în care o rulare cere ceva operatorului. Afișează un card numerotat în conversație și blochează până când cineva răspunde, omite sau întrebarea expiră. Nu scrie niciodată întrebarea ca mesaj de chat — asta încheie tura.

Argument	Semnificație
question	Ce să întrebi
context	Opțional: de ce întrebi și ce depinde de răspuns
options[]	Opțiuni, fiecare {label, description?}
allow_free_text	Dacă se acceptă un răspuns tastat
multi_select	Dacă se pot alege mai multe opțiuni

O omitere este un succes: continuă pe baza unei presupuneri declarate și nu mai întreba din nou. Expirarea este o eroare cu aceeași instrucțiune. Solicitările de permisiune („pot să fac asta?”) sunt o poartă separată și se afișează ca același card în conversație.

Înregistrat doar când există atât un port de întrebări, cât și un spațiu țintă. Fără un om atașat, apelul eșuează în loc să blocheze la nesfârșit — aceeași postură cu eșec închis pe care o adoptă un prompt de guardrail când nu este conectat niciun aprobator.

---

vibe_* — dirijarea workerilor din fundal

Înregistrate doar cât timp modul vibe este activ. Toate cinci sunt de nivel read: poarta aparține instrumentelor workerului, acolo unde se produce de fapt editarea.

Instrument	Argumente	Note
vibe_spawn	brief, label, tier?	Se întoarce imediat; workerul rulează în continuare
vibe_send	worker_id, message	Adaugă la brief și rulează din nou
vibe_wait	worker_id, timeout_seconds?	Blochează până când se stabilizează
vibe_kill	worker_id	Îl oprește
vibe_list	—	Nivel, stare, timp scurs și ultimul rezultat

tier este fast (muncă mecanică cu o specificație clară) sau good (proiectare, judecată sau revizuirea rezultatului unui worker fast).