بلٹ اِن ایجنٹ ٹولز

یہ وہ سرور سے بندھے ٹولز ہیں جو بلٹ اِن ایجنٹ رن ٹائم براہِ راست رجسٹر کرتا ہے — لینگویج سرور، ساختی تلاش، ڈی بگر، کرنل، سوالات اور ورکر کنٹرول — بخلاف اُن MCP ٹولز کے جو وہ برج کے ذریعے جوڑتا ہے، اور ہارنس رن ٹائم کے عام فائل، تلاش اور شیل ٹولز کے۔ یہ MCP رجسٹری پر نہیں ہیں: کوئی بیرونی MCP کلائنٹ انہیں نہیں دیکھے گا، کیونکہ ہر ایک سرور کی جانب موجود کسی زندہ وسیلے سے بندھا ہوتا ہے — ایک لینگویج سرور پروسیس، ایک ڈی بگ اڈاپٹر، ایک انٹرپریٹر — جو کسی ایک رن کا ہوتا ہے۔

یہاں ہر ٹول صرف اُس وقت رجسٹر ہوتا ہے جب اُس کا پشت پناہ وسیلہ اُس رن کے لیے جڑا ہو — لینگویج سرور یا ڈی بگ سپروائزر، ایک ٹری-سِٹر پارسر، ایک کرنل فیکٹری، ایک سوال پورٹ، ایک vibe راسٹر۔ اِس چیک آؤٹ کے لیے لینگویج سرور یا ڈی بگ اڈاپٹر کی پہچان ایک الگ، بعد کی جانچ ہے (status / adapters): وہ ٹولز سطح پر موجود رہتے ہیں تاکہ ایجنٹ اندازہ لگانے کے بجائے پوچھ سکے کہ کچھ بھی قابلِ استعمال کیوں نہیں۔

منظوری کے درجے

ہر ٹول ایک درجہ قرار دیتا ہے، اور درجہ ہی طے کرتا ہے کہ اُسے کون سی سطحیں دیکھتی ہیں — نہ کہ صرف یہ کہ وہ پرامپٹ کرتا ہے یا نہیں۔ پلان موڈ اور صرف پڑھنے والے ذیلی ایجنٹس read تک محدود رہتے ہیں، اس لیے write یا exec درجے کا ٹول اُن کے اسکیما سے مکمل طور پر غائب ہوتا ہے۔

درجہ	مطلب	یہاں کے ٹولز
read	کوئی ضمنی اثر نہیں	lsp, ast_grep, ask_user, پانچوں vibe_*
write	فائلیں بدلتا ہے	lsp_rename, ast_edit, resolve
exec	کوئی پروسیس شروع یا کنٹرول کرتا ہے	debug, eval

---

lsp — لینگویج سرور کوئریز

اُس وقت رجسٹر ہوتا ہے جب رن کے پاس لینگویج سرور سپروائزر اور ایک ورکنگ ڈائریکٹری ہو۔ سرور واقعی جواب دے سکتا ہے یا نہیں، یہ کال کے وقت ایک تقاطع کے طور پر پہچانا جاتا ہے: روٹ مارکر کا موجود ہونا لازم ہے اور سرور بائنری کا حل ہونا بھی۔ صرف ایک کا ہونا یعنی کوئی سرور شروع نہیں ہوتا — status یہی بتاتا ہے — خاموش اندازے کے بجائے۔

پوزیشنیں line کے ساتھ symbol کے سب اسٹرنگ سے مخاطب کی جاتی ہیں، کالم سے کبھی نہیں۔ جس ماڈل سے کالم مانگا جائے وہ اندازہ لگاتا ہے، اور غلط اندازہ اُسی لائن کے کسی مختلف علامت پر اتر آتا ہے — ایسا جواب جو درست لگتا ہے مگر کسی اور چیز کے بارے میں ہے۔ نیویگیشن ایکشن پر symbol چھوڑ دینا ایک خرابی ہے، پہلے کالم کا اندازہ نہیں۔

ایکشن	آرگیومنٹس	واپسی
diagnostics	file (یا "*")	ایررز اور وارننگز؛ "*" اُس کے بجائے پروجیکٹ چیکر چلاتا ہے
definition	file, line, symbol	جہاں علامت کا اعلان کیا گیا ہے
type_definition	file, line, symbol	جہاں اُس کے ٹائپ کا اعلان کیا گیا ہے
implementation	file, line, symbol	ٹھوس اپلیمنٹیشنز
references	file, line, symbol	ہر استعمال، زیادہ سے زیادہ 50
hover	file, line, symbol	سگنیچر اور ڈاک کمینٹ
symbols	query یا file	query کے ساتھ ورک اسپیس تلاش (حد 100)؛ file کے ساتھ دستاویزی علامات (حد 200)
code_actions	file, line, symbol	سرور کی پیش کردہ فوری اصلاحات
status	—	کون سے سرور چل رہے ہیں، اور کون سے روٹس کے لیے
reload	—	اِس روٹ کے لیے سرور دوبارہ شروع کرتا ہے

تحریر پر تشخیصات

اصل فائدہ ٹول نہیں ہے۔ write، edit اور apply_patch لپیٹے ہوئے ہیں: تحریر کے بعد فائل لینگویج سرور کے ذریعے سنک اور محفوظ ہوتی ہے، اور صرف نئی سامنے آنے والی تشخیصات ٹول کے نتیجے میں شامل کی جاتی ہیں۔ ایجنٹ کو اُسی لمحے پتہ چل جاتا ہے جب اُس نے بلڈ توڑا، بغیر یہ یاد رکھنے کے کہ پوچھنا تھا۔

پہلے بتائی جا چکی تشخیصات کو فی رن ایک لیجر دبا دیتا ہے جو شدت، کوڈ اور پیغام کی بنیاد پر کلید بندھا ہوتا ہے — پوزیشن جان بوجھ کر خارج، تاکہ جو تشخیص صرف چار لائن نیچے سرک گئی ہو، اُسے نئی کہہ کر دوبارہ نہ بتایا جائے۔

lsp_rename — پورے پروجیکٹ میں نام کی تبدیلی

ایک الگ، write درجے کا ٹول، بالکل ایک ہی وجہ سے: درجہ ہی نظر آنا طے کرتا ہے۔ نام کی تبدیلی کو lsp میں سمو دینا یا تو صرف پڑھنے والے ایکسپلورر کو ریپو دوبارہ لکھنے کی اہلیت دے دیتا، یا ہر hover کو منظوری کے پرامپٹ کے پیچھے ڈال دیتا۔

آرگیومنٹ	مطلب
file	جہاں علامت ہے
line	1-انڈیکس والی لائن
symbol	اُس لائن پر اسے پہچاننے والا سب اسٹرنگ
new_name	اُسے کیا کہا جائے

---

ast_grep — ساختی تلاش

کوڈ کو متن کے بجائے شکل سے ڈھونڈتا ہے۔ $NAME کسی بھی نوڈ سے میل کھاتا ہے، $$$NAME بہن بھائیوں کی کسی قطار سے، اور $_ ایسا وائلڈ کارڈ ہے جو کچھ نہیں باندھتا۔

وہ خاصیت جو اسے چند اضافی قدموں والا ریجیکس بننے سے روکتی ہے: ایک ہی پیٹرن میں دہرایا گیا میٹا متغیر لازماً وہی متن پکڑتا ہے۔

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

ایسی گارڈ سے میل کھاتا ہے جو اُسی چیز کو ڈسپوز کرتی ہے جس کی اُس نے جانچ کی تھی، اور ایسی گارڈ سے میل نہیں کھاتا جو کسی اور چیز کو ڈسپوز کرے۔

آرگیومنٹ	مطلب
pattern	میٹا متغیرات والا کوڈ ٹکڑا
path	تلاش کے لیے فائل یا ڈائریکٹری؛ ڈیفالٹ پورا ورک اسپیس
language	کوئی فراہم کردہ گرامر آئی ڈی (dart, python, rust, c, …)۔ جب path کسی فائل کا نام ہو تو خود اخذ ہو جاتی ہے
max_results	ڈیفالٹ 50

پیٹرن اُسی گرامر سے پارس ہوتا ہے جس سے فائل

چنانچہ dispose(x) اُس کال سے میل کھاتا ہے، خواہ وہ کسی بھی طرح فاصلے، لپیٹ یا تبصرے میں ہو — اور سٹرنگ لٹرل یا تبصرے کے اندر انہی حروف سے کبھی میل نہیں کھاتا۔

ٹکڑا ننگے طور پر نہیں، ایک سکیفولڈ میں پارس ہوتا ہے

Dart کے ٹاپ لیول پر پارس کیا گیا dispose(x) ایک درست فنکشن سگنیچر ہے۔ پیٹرن کمپائلر سیاق و سباق کی ایک سیڑھی آزماتا ہے (سٹیٹمنٹ، ایکسپریشن، کلاس ممبر، اعلان) اور جو پہلا ٹکڑے کو قبول کر لے، وہی استعمال کرتا ہے۔ جس پیٹرن کو کوئی سیاق قبول نہ کرے، اُسے تلاش کر کے خاموشی سے نہ پائے جانے کے بجائے ناقابلِ پارس بتا دیا جاتا ہے۔

ast_edit — ساختی ری رائٹ، اسٹیج شدہ

وہی میچنگ، باضافہ ایک rewrite ٹیمپلیٹ جس میں میٹا متغیرات واپس شامل کر دیے جاتے ہیں۔ کچھ بھی نہیں لکھا جاتا۔ تبدیلی اسٹیج کر دی جاتی ہے اور نتیجہ ایک 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"

آرگیومنٹ	مطلب
pattern	کس سے میل کھانا ہے
rewrite	وہاں کیا رکھنا ہے، $NAME شامل کر کے
path	دائرہ کار؛ ڈیفالٹ پورا ورک اسپیس
language	زبان کی آئی ڈی

resolve — اسٹیج شدہ تبدیلی کمٹ یا مسترد کریں

آرگیومنٹ	مطلب
edit_id	(proposed) نتیجے سے
action	accept یا discard

ہر فائل کا موازنہ اسٹیجنگ کے وقت محفوظ کیے گئے مواد سے کیا جاتا ہے، اور کوئی بھی عدم مطابقت پوری تبدیلی کو مسترد کر دیتی ہے۔ ادھورا لاگو ہوا ساختی ری رائٹ ایسا درخت چھوڑتا ہے جو نہ پرانی شکل میں کمپائل ہوتا ہے نہ نئی میں۔

---

debug — ڈی بگر چلائیں

اُس وقت رجسٹر ہوتا ہے جب رن کے پاس ڈی بگ سیشن سپروائزر، ایک ورکنگ ڈائریکٹری اور ایک گفتگو آئی ڈی ہو۔ اڈاپٹر واقعی شروع ہو سکتا ہے یا نہیں، یہ کال کے وقت اُسی تقاطع اصول سے پہچانا جاتا ہے جو لینگویج سرور کا ہے (روٹ مارکر اور بائنری)۔ exec درجہ؛ متوازی کے لیے محفوظ نہیں (سیشن کالز کے درمیان حالت ہوتا ہے، چنانچہ stack سے آگے نکل جانے والا continue ایسا فریم پڑھے گا جو آگے بڑھ چکا ہوگا)۔

فی گفتگو ایک سیشن، سخت TTL کے ساتھ (30 منٹ)۔ دوسری launch خاموشی سے پہلی کی جگہ لینے کے بجائے مسترد کر دی جاتی ہے۔

آپریشن	آرگیومنٹس	نوٹس
adapters	—	یہاں کون سے اڈاپٹرز قابلِ استعمال ہیں، اور کیوں نہیں
status	—	کوئی سیشن چل رہا ہے یا نہیں، اور کہاں رکا
breakpoints	file, lines[]	خالی lines فائل صاف کر دیتا ہے۔ لانچ کرنے سے پہلے سیٹ کیا جا سکتا ہے
launch	program, args[]	پروگرام کو آپ کے بریک پوائنٹس پر رکا ہوا شروع کرتا ہے
attach	port	پہلے سے چل رہے ڈی بگی سے جڑتا ہے
continue	thread_id?	اگلے اسٹاپ تک چلتا ہے
pause	thread_id?	اسے وہیں روک دیتا ہے جہاں ہے
step_over / step_in / step_out	thread_id?	ایک قدم آگے بڑھاتا ہے
threads	—	تھریڈ آئی ڈیز اور نام
stack	thread_id?	فریمز، زیادہ سے زیادہ 30
scopes	frame_id	ایک فریم پر اسکوپس، ہر ایک کے ساتھ ایک reference
variables	reference	بچے، حد 50، ویلیوز حد 400 حروف
evaluate	expression, frame_id?	فریم کے اپنے اسکوپ میں جانچا گیا
output	—	ڈی بگی کی stdout/stderr، محدود
terminate	—	سیشن ختم کرتا ہے اور اڈاپٹر مار ڈالتا ہے

اڈاپٹرز

آئی ڈی	کمانڈ	روٹ مارکرز
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 پروجیکٹ کے اندر موجود .venv/bin یا venv/bin کو $PATH پر ترجیح دیتا ہے: $PATH والا python ایک مختلف ماحول ہوتا ہے، اور غلط والے سے اٹیچ کرنا ایسے انداز میں ناکام ہوتا ہے جو ٹوٹے ہوئے کوڈ جیسا لگتا ہے۔

---

eval — مستقل انٹرپریٹرز

ایک Python یا JavaScript سیل جس کے ویری ایبلز، امپورٹس اور لوڈ شدہ ڈیٹا کالز کے درمیان برقرار رہتے ہیں۔ exec درجہ؛ متوازی کے لیے محفوظ نہیں۔

آرگیومنٹ	مطلب
code	سیل
description	لازمی۔ ٹرانسکرپٹ لیبل کے لیے 5–10 الفاظ
language	python (ڈیفالٹ) یا javascript
reset	انٹرپریٹر رد کر کے پہلے صاف سا شروع کرتا ہے

• آخری ایکسپریشن ویسے ہی ظاہر ہوتا ہے جیسے نوٹ بک کرتی ہے۔
• display() کام کرتا ہے، pandas فریم ٹیبل کی صورت میں رینڈر ہوتا ہے، اور matplotlib فگر ایک تصویر کی صورت میں واپس آتا ہے جسے ٹرانسکرپٹ دکھاتا ہے۔
• وہ IPython محاورے جو لوگ بے ساختہ ٹائپ کرتے ہیں — %pip، %cd، !cmd، %%bash، %%timeit — سادہ کوڈ میں دوبارہ لکھ دیے جاتے ہیں۔ %pip ساتھ ہی sys.modules سے بھی نکال دیتا ہے، تاکہ اگلا import وہی دیکھے جو ابھی انسٹال ہوا۔

سیل کے اندر سے اپنے ٹولز کال کرنا

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

برج ہارنس ٹول رجسٹری میں دوبارہ داخل ہوتا ہے، اس لیے گارڈریلز، منظوری اور ہر ریپر بالکل ویسے ہی لاگو ہوتے ہیں جیسے ماڈل کی جاری کردہ کال پر۔ یہ لوپ بیک ساکٹ کے بجائے کرنل کے اپنے پائپ پر سوار ہوتا ہے: نہ کوئی پورٹ، نہ کوئی راز، نہ کوئی اگریس اصول۔

سیل کا ٹائم آؤٹ ایک غیر فعالیت کا بجٹ ہے (ڈیفالٹ 5 منٹ) اور جب تک کوئی برج کے ذریعے کی گئی کال زیر التوا ہو، وہ معطل رہتا ہے، چنانچہ جو سیل سب ایجنٹس تک پھیلے، وہ پھیلاؤ کے بیچ مارا نہیں جاتا۔

کرنل کہاں چلتا ہے

گفتگو کا انکلوژر ہو تو اُسی میں، ورنہ ہوسٹ پر۔ یہ وہاں تک پہنچنے کے لیے انکلوژر بوٹ نہیں کرتا — وہی اصول جو رگ ٹیب کو خودکار شروع ہونے سے روکتا ہے۔

---

ask_user — انسان سے سوال پوچھیں

read درجہ۔ کسی رن کا آپریٹر سے کچھ پوچھنے کا واحد طریقہ۔ یہ گفتگو میں نمبر والا کارڈ دکھاتا ہے اور جب تک کوئی جواب نہ دے، نہ چھوڑے، یا سوال ٹائم آؤٹ نہ ہو جائے، رکتا ہے۔ سوال کو کبھی چیٹ پیغام کے طور پر نہ لکھیں — وہ ٹرن ختم کر دیتا ہے۔

آرگیومنٹ	مطلب
question	کیا پوچھنا ہے
context	اختیاری: آپ کیوں پوچھ رہے ہیں اور جواب پر کیا منحصر ہے
options[]	انتخاب، ہر ایک {label, description?}
allow_free_text	آیا ٹائپ کیا گیا جواب قبول کیا جاتا ہے
multi_select	آیا کئی اختیار چنے جا سکتے ہیں

چھوڑ دینا کامیابی ہے: ایک بیان کردہ مفروضے پر آگے بڑھیں اور دوبارہ نہ پوچھیں۔ ٹائم آؤٹ ایک خرابی ہے، اُسی ہدایت کے ساتھ۔ اجازت کے پرامپٹس (”کیا میں یہ کر سکتا ہوں؟“) ایک الگ چوک پوائنٹ ہیں اور گفتگو میں وہی کارڈ دکھاتے ہیں۔

صرف اُس وقت رجسٹر ہوتا ہے جب سوال پورٹ اور ہدف اسپیس، دونوں موجود ہوں۔ کوئی انسان منسلک نہ ہو تو کال ہمیشہ کے لیے رکنے کے بجائے ناکام ہو جاتی ہے — وہی بند ہو کر ناکام ہونے کا رویہ جو کوئی گارڈریل prompt کوئی منظور کنندہ منسلک نہ ہونے پر اپناتا ہے۔

---

vibe_* — پس منظر ورکرز کی ہدایت

صرف اُس وقت رجسٹر ہوتے ہیں جب vibe موڈ آن ہو۔ پانچوں read درجے کے ہیں: گیٹ ورکر کے ٹولز پر ہونا چاہیے، جہاں ترمیم واقعی ہوتی ہے۔

ٹول	آرگیومنٹس	نوٹس
vibe_spawn	brief, label, tier?	فوراً واپس آ جاتا ہے؛ ورکر چلتا رہتا ہے
vibe_send	worker_id, message	بریف میں شامل کر کے دوبارہ چلاتا ہے
vibe_wait	worker_id, timeout_seconds?	جب تک وہ اپنا کام ختم نہ کر لے رکتا ہے
vibe_kill	worker_id	اسے روک دیتا ہے
vibe_list	—	درجہ، حیثیت، گزرا ہوا وقت اور آخری نتیجہ

tier یا fast ہے (واضح تفصیل والا مکینیکل کام) یا good (ڈیزائن، فیصلہ سازی، یا کسی fast ورکر کے آؤٹ پٹ کا جائزہ)۔