کمانڈ کی قطار (2026-01-16)¶

ہم اندر آنے والی آٹو-ریپلائی رنز (تمام چینلز) کو ایک چھوٹی اِن-پروسیس قطار کے ذریعے سلسلہ وار بناتے ہیں تاکہ متعدد ایجنٹ رنز کے باہمی تصادم سے بچا جا سکے، جبکہ سیشنز کے درمیان محفوظ متوازی عمل بھی برقرار رہے۔

کیوں¶

• آٹو-ریپلائی رنز مہنگی ہو سکتی ہیں (LLM کالز) اور جب متعدد اندر آنے والے پیغامات قریب قریب وقت میں پہنچیں تو ٹکرا سکتی ہیں۔
• سلسلہ وار بنانا مشترکہ وسائل (سیشن فائلیں، لاگز، CLI stdin) کے لیے مقابلہ کم کرتا ہے اور اپ اسٹریم ریٹ لمٹس کے امکانات گھٹاتا ہے۔

یہ کیسے کام کرتا ہے¶

• لین سے باخبر FIFO قطار ہر لین کو قابلِ کنفیگ ہم وقتی حد کے ساتھ خالی کرتی ہے (غیر کنفیگر شدہ لینز کے لیے بطورِ طے شدہ 1؛ main بطورِ طے شدہ 4، subagent کے لیے 8)۔
• runEmbeddedPiAgent سیشن کلید (لین session:<key>) کے ذریعے قطار میں ڈالتا ہے تاکہ فی سیشن صرف ایک فعال رن کی ضمانت ہو۔
• پھر ہر سیشن رن کو ایک عالمی لین (بطورِ طے شدہ main) میں قطار بند کیا جاتا ہے تاکہ مجموعی متوازی عمل agents.defaults.maxConcurrent کے ذریعے محدود رہے۔
• جب verbose لاگنگ فعال ہو، تو قطار میں موجود رنز اگر شروع ہونے سے پہلے ~2s سے زیادہ انتظار کریں تو ایک مختصر نوٹس خارج کرتے ہیں۔
• ٹائپنگ اشارے قطار میں ڈالنے پر فوراً فائر ہو جاتے ہیں (جب چینل سپورٹ کرے)، اس طرح باری کے انتظار کے دوران صارف تجربہ برقرار رہتا ہے۔

قطار کے موڈز (ہر چینل کے لیے)¶

اندر آنے والے پیغامات موجودہ رن کو steer کر سکتے ہیں، فالو اپ ٹرن کا انتظار کر سکتے ہیں، یا دونوں کر سکتے ہیں:

• 30. اگر streaming نہ ہو تو followup پر واپس چلا جاتا ہے۔ 31. collect: تمام قطار میں موجود پیغامات کو ایک واحد followup ٹرن میں یکجا کرتا ہے (ڈیفالٹ)۔
• followup: موجودہ رن کے ختم ہونے کے بعد اگلے ایجنٹ ٹرن کے لیے قطار میں ڈالیں۔
• 32. اگر پیغامات مختلف چینلز/تھریڈز کو ہدف بناتے ہوں تو روٹنگ برقرار رکھنے کے لیے وہ الگ الگ drain ہوتے ہیں۔ 33. Steer‑backlog کا مطلب ہے کہ steered run کے بعد آپ کو followup جواب مل سکتا ہے، اس لیے streaming سطحیں ڈپلیکیٹس جیسی لگ سکتی ہیں۔
• steer-backlog (عرف steer+backlog): ابھی steer کریں اور پیغام کو فالو اپ ٹرن کے لیے محفوظ رکھیں۔
• interrupt (legacy): اس سیشن کے لیے فعال رن کو منسوخ کریں، پھر تازہ ترین پیغام چلائیں۔
• queue (legacy alias): steer جیسا ہی۔

34. اگر آپ ہر آنے والے پیغام پر ایک ہی جواب چاہتے ہیں تو collect/steer کو ترجیح دیں۔ 35. /queue collect کو ایک standalone کمانڈ کے طور پر (فی سیشن) بھیجیں یا messages.queue.byChannel.discord: "collect" سیٹ کریں۔
35. /queue collect کو ایک علیحدہ کمانڈ کے طور پر (فی سیشن) بھیجیں یا messages.queue.byChannel.discord: "collect" سیٹ کریں۔

Defaults (جب کنفیگ میں سیٹ نہ ہوں):

• تمام سرفیسز → collect

messages.queue کے ذریعے عالمی یا فی چینل کنفیگر کریں:

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

Queue options¶

اختیارات followup، collect، اور steer-backlog پر لاگو ہوتے ہیں (اور steer پر بھی جب وہ فالو اپ پر واپس جائے):

• debounceMs: فالو اپ ٹرن شروع کرنے سے پہلے خاموشی کا انتظار کریں ( “continue, continue” سے بچاتا ہے)۔
• cap: فی سیشن زیادہ سے زیادہ قطار بند پیغامات۔
• drop: اوورفلو پالیسی (old، new، summarize)۔

37. ڈیفالٹس: debounceMs: 1000, cap: 20, drop: summarize۔
38. سیشن pruning ہر LLM کال سے عین پہلے in‑memory context سے پرانے tool نتائج کو تراش دیتی ہے۔

Per-session overrides¶

• موجودہ سیشن کے لیے موڈ محفوظ کرنے کو /queue <mode> بطورِ واحد کمانڈ بھیجیں۔
• اختیارات یکجا کیے جا سکتے ہیں: /queue collect debounce:2s cap:25 drop:summarize
• /queue default یا /queue reset سیشن اووررائیڈ صاف کر دیتا ہے۔

Scope and guarantees¶

• گیٹ وے ریپلائی پائپ لائن استعمال کرنے والے تمام اندر آنے والے چینلز پر آٹو-ریپلائی ایجنٹ رنز پر لاگو ہوتا ہے (WhatsApp web، Telegram، Slack، Discord، Signal، iMessage، webchat، وغیرہ)۔
• بطورِ طے شدہ لین (main) اندر آنے والے + main ہارٹ بیٹس کے لیے پروسیس-وائیڈ ہے؛ متعدد سیشنز کو متوازی اجازت دینے کے لیے agents.defaults.maxConcurrent سیٹ کریں۔
• اضافی لینز موجود ہو سکتی ہیں (مثلاً cron، subagent) تاکہ پسِ منظر جابز اندر آنے والے جوابات کو بلاک کیے بغیر متوازی چل سکیں۔
• فی سیشن لینز اس بات کی ضمانت دیتی ہیں کہ کسی مخصوص سیشن کو ایک وقت میں صرف ایک ایجنٹ رن چھوئے۔
• کوئی بیرونی انحصارات یا بیک گراؤنڈ ورکر تھریڈز نہیں؛ خالص TypeScript + promises۔

Troubleshooting¶

• اگر کمانڈز رکی ہوئی محسوس ہوں، تو verbose لاگز فعال کریں اور “queued for …ms” والی سطریں دیکھیں تاکہ قطار کے خالی ہونے کی تصدیق ہو۔
• اگر آپ کو قطار کی گہرائی درکار ہو، تو verbose لاگز فعال کریں اور قطار کے ٹائمنگ والی سطروں پر نظر رکھیں۔