@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ar-SA/messaging.md

@@ -0,0 +1,461 @@
+---
+title: "المراسلة"
+description: "تحدث إلى وكيلك من Slack أو البريد الإلكتروني أو Telegram أو WhatsApp - نفس الوكيل، نفس الذاكرة، نفس الأدوات."
+---
+
+# المراسلة
+
+قم بتوصيل وكيلك بـ Slack أو البريد الإلكتروني أو Telegram أو WhatsApp حتى تتمكن من الدردشة معه من التطبيقات التي تستخدمها بالفعل. إنه نفس الوكيل - نفس الذاكرة، نفس الأدوات، نفس المواضيع - يمكن الوصول إليه من أماكن أكثر.
+
+> **هل تستخدم قالب الإرسال؟** تم إعداد كل هذا لك في **الإعدادات → المراسلة**. انقر لربط كل نظام أساسي — لن تحتاج إلى قراءة بقية هذه الصفحة إلا إذا كنت تقوم بتخصيص القالب الخاص بك أو إنشائه. راجع [Dispatch](/docs/dispatch) أو [Dispatch template reference](/docs/template-dispatch).
+
+## ما يمكنك فعله {#what-you-can-do}
+
+- **أرسل بريدًا إلكترونيًا إلى وكيلك** على عنوان مثل `agent@yourcompany.com` — حيث يتم الرد داخل سلسلة الرسائل، تمامًا كما يفعل زميل العمل.
+- **إرسال رسالة إلى وكيلك** في سلسلة رسائل — ستتم قراءتها والتفاعل معك عندما تطلب ذلك.
+- **إرسال رسالة مباشرة للوكيل على Slack**، أو `@mention` في أي قناة.
+- **راسل الوكيل على Telegram أو WhatsApp** من هاتفك.
+- **نفس الوكيل، نفس الذاكرة.** كل ما تقوله على Slack يتم تذكره عندما ترسله بالبريد الإلكتروني لاحقًا. تشترك دردشة الويب والرسائل الخارجية في سجل موضوع واحد.
+- للحصول على تنبيهات أحادية الاتجاه داخل التطبيق (رمز الجرس، webhooks)، راجع [Notifications](/docs/notifications).
+
+```an-diagram title="Many channels, one agent" summary="Every platform fans into the same agent loop and the same SQL thread history — so a Slack DM and an email continue the same conversation."
+{
+  "html": "<div class=\"msg-fanin\"><div class=\"diagram-col\"><div class=\"diagram-node\">Slack</div><div class=\"diagram-node\">Email</div><div class=\"diagram-node\">Telegram</div><div class=\"diagram-node\">WhatsApp</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">One agent loop</span><small class=\"diagram-muted\">same memory · same tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>One SQL thread history<br><small class=\"diagram-muted\">web chat + external messages share it</small></div></div>",
+  "css": ".msg-fanin{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.msg-fanin .diagram-col{display:flex;flex-direction:column;gap:8px}.msg-fanin .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## إعداد Slack {#slack}
+
+### ما ستحتاج إليه
+
+- مساحة عمل Slack حيث يمكنك تثبيت التطبيقات (وصول المشرف)
+- حوالي 5 دقائق
+
+### الخطوات
+
+1. انتقل إلى **[api.slack.com/apps](https://api.slack.com/apps)** وانقر على **إنشاء تطبيق جديد** → **من البداية**. أطلق عليه اسمًا (على سبيل المثال، "الوكيل") واختر مساحة العمل الخاصة بك.
+2. في الشريط الجانبي الأيسر، افتح **OAuth والأذونات**. ضمن **نطاقات الرموز المميزة للبوت**، أضف:
+   - `chat:write` — يتيح للوكيل إرسال الرسائل
+   - `app_mentions:read` — يتيح للوكيل معرفة متى يتم ذكره @ (اختياري)
+   - `im:history` — يتيح للوكيل قراءة الرسائل المباشرة المرسلة إليه
+   - `assistant:write` — اختياري؛ يتيح لـ Slack عرض حالة "يفكر..." الأصلية في سلاسل الرسائل المساعدة
+   - `users:read.email` — اختياري؛ تساعد القوالب مثل البريد في التحقق من البريد الإلكتروني للمرسل Slack للحصول على هوية قائمة انتظار المسودة
+3. انقر فوق **التثبيت على مساحة العمل** أعلى تلك الصفحة. سوف يمنحك Slack **رمز Bot User OAuth** الذي يبدأ بـ `xoxb-`. انسخه.
+4. انتقل إلى **المعلومات الأساسية** في الشريط الجانبي وانسخ **سر التوقيع**.
+5. افتح إعدادات تطبيقك (أو لوحة متغيرات البيئة الخاصة بموفر الاستضافة) والصق:
+   - `SLACK_BOT_TOKEN` — الرمز المميز `xoxb-…`
+   - `SLACK_SIGNING_SECRET` — سر التوقيع
+   - `SLACK_ALLOWED_TEAM_IDS` — موصى به في الإنتاج؛ يُسمح بمعرفات مساحة العمل/الفريق Slack المفصولة بفواصل بإرسال الأحداث
+   - `SLACK_ALLOWED_API_APP_IDS` — موصى به لتطبيقات مساحات العمل المتعددة؛ يُسمح لمعرفات تطبيقات Slack المفصولة بفواصل باستخدام سر التوقيع هذا
+6. بالعودة إلى Slack، افتح **اشتراكات الأحداث**، وقم بتشغيلها، ثم الصق هذا الطلب URL:
+
+   ```نص
+   https://your-app.example.com/_agent-native/integrations/slack/webhook
+   ```
+
+   ثم ضمن **الاشتراك في أحداث الروبوت**، أضف `message.im` (للرسائل المباشرة) واختياريًا `app_mention` (لإشارات القناة). احفظ.
+
+7. أرسل إلى الروبوت الخاص بك رسالة مباشرة في Slack. ينبغي الرد.
+
+### اختياري: يتم فتح التطبيق
+
+يتيح تطبيق Slack للتطبيق استبدال معاينة الرابط العادي لـ Slack بمعاينة أكثر ثراءً
+معاينة. يستخدم Clips هذا لمعاينات الفيديو القابلة للتشغيل بنمط Loom.
+
+أضف نطاقات الروبوت الإضافية هذه عندما يحتاج تطبيقك إلى النشر:
+
+- `links:read` - يتيح لـ Slack إخطار التطبيق عند نشر النطاقات المسجلة
+- `links:write` - يتيح للتطبيق استبدال المعاينة الافتراضية لـ Slack
+- `links.embed:write` - يتيح للتطبيق تضمين الوسائط/المشغل المعتمد URLs
+
+ثم اشترك في حدث `link_shared` وقم بتسجيل نطاقات التطبيق العامة الخاصة بك
+ضمن **مجالات فتح التطبيق**. بالنسبة للمعاينات القابلة للتشغيل لـ Clips فقط، قم بتعيين Slack
+اطلب اشتراكات الأحداث URL إلى:
+
+```text
+https://your-clips.example.com/api/slack/unfurl
+```
+
+يحتوي تطبيق Slack على طلب API واحد للأحداث وهو URL. إذا كان يجب على نفس تطبيق Slack التعامل مع
+يتم نشر كل من أحداث محادثة الوكيل والمقاطع، وتوجيه أحداث Slack من خلال
+المرسل الذي يرسل أحداث الرسالة إلى `/_agent-native/integrations/slack/webhook`
+وأحداث `link_shared` إلى معالج نشر Clips.
+
+### نصائح
+
+- **إشارات القناة** — لا يستجيب الروبوت إلا في القنوات عندما تتم الإشارة إليها بال@، وذلك لتجنب الضوضاء.
+- **الرسائل المباشرة** — يتم التعامل مع كل رسالة مباشرة على أنها محادثة خاصة مع الوكيل.
+- **نفس الهوية، جميع القنوات** — إذا كان مستخدم Slack لديه نفس البريد الإلكتروني كمستخدم مسجل في تطبيقك، فسيعامله الوكيل على أنه نفس الشخص.
+- **قوائم الإنتاج المسموح بها** — قم بتعيين `SLACK_ALLOWED_TEAM_IDS`، وبالنسبة لتطبيقات Slack المشتركة، `SLACK_ALLOWED_API_APP_IDS` بحيث لا يمكن إعادة استخدام سر التوقيع الصالح بواسطة مساحة عمل غير متوقعة.
+- **نشر تطبيق Clips** — تستخدم مقاطع Agent-Native القابلة للتثبيت لـ Slack `SLACK_CLIENT_ID`، و`SLACK_CLIENT_SECRET`، و`SLACK_SIGNING_SECRET`، و`/api/slack/oauth/callback`. تحصل كل مساحة عمل Slack متصلة على رمز الروبوت المشفر الخاص بها في `app_secrets`؛ `SLACK_BOT_TOKEN` ما هو إلا نسخة احتياطية قديمة لمساحة عمل واحدة.
+
+## إعداد تيليجرام {#telegram}
+
+### ما ستحتاج إليه
+
+- تطبيق Telegram على هاتفك
+- حوالي 3 دقائق
+
+### الخطوات
+
+1. افتح تيليجرام وأرسل رسالة **[@BotFather](https://t.me/BotFather)**.
+2. أرسل `/newbot` واتبع المطالبات لتسمية الروبوت الخاص بك. سوف يقوم BotFather بالرد باستخدام **رمز HTTP API**. انسخه.
+3. في متغيرات بيئة تطبيقك، قم بتعيين:
+   - `TELEGRAM_BOT_TOKEN` — الرمز المميز من BotFather
+4. بعد النشر، قم بتسجيل خطاف الويب بواسطة `POST`ing في تطبيقك على:
+
+   ```نص
+   POST https://your-app.example.com/_agent-native/integrations/telegram/setup
+   ```
+
+   يؤدي هذا إلى مطالبة Telegram بإرسال رسائل إلى خطاف الويب الخاص بتطبيقك. ما عليك سوى القيام بذلك مرة واحدة في كل عملية نشر.
+
+5. ابحث عن الروبوت الخاص بك في Telegram (ابحث عن اسم المستخدم الذي قدمه لك BotFather) وأرسل إليه رسالة.
+
+## إعداد البريد الإلكتروني {#email}
+
+يعد البريد الإلكتروني أقوى عملية تكامل - حيث يحصل وكيلك على عنوانه الخاص، ويرد عليه في سلسلة المحادثات، ويمكن إرسال نسخة إليه في المحادثات، ويستخدم البريد الإلكتروني للمرسل كهوية له. لا حاجة لأمر `/link`.
+
+### ما ستحتاج إليه
+
+- النطاق الذي تتحكم فيه (أو يمكنك استخدام نطاق فرعي مجاني لإعادة الإرسال - انظر أدناه)
+- حساب به **Resend** أو **SendGrid** للتعامل مع البريد الوارد والبريد الصادر
+- حوالي 10 دقائق
+
+### الخطوات (مع إعادة الإرسال — الأسهل)
+
+1. قم بالتسجيل في **[resend.com](https://resend.com)**. الطبقة المجانية كافية للبدء.
+2. اختر الشكل الذي سيبدو عليه عنوان البريد الإلكتروني للوكيل:
+   - **الأسهل:** استخدام عنوان `<your-slug>.resend.app` مجاني — لا حاجة إلى DNS.
+   - **العلامة التجارية:** أضف نطاقًا مخصصًا (مثل `yourcompany.com`) في صفحة **النطاقات** الخاصة بإعادة الإرسال واتبع خطوات DNS.
+3. في إعادة الإرسال، افتح **Webhooks** → **إضافة نقطة نهاية** وأشر إليها:
+
+   ```النص
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+   اشترك في حدث **`email.received`**. ستمنحك إعادة الإرسال سر التوقيع — انسخه.
+
+4. في متغيرات بيئة تطبيقك، قم بتعيين:
+   - `EMAIL_AGENT_ADDRESS` — العنوان الذي يتلقى الوكيل البريد عليه (على سبيل المثال، `agent@yourcompany.com`)
+   - `RESEND_API_KEY` — مفتاح إعادة إرسال API الخاص بك
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` — سر التوقيع من إعادة الإرسال (موصى به؛ يستخدم للتحقق من التوقيع)
+
+5. أرسل بريدًا إلكترونيًا إلى عنوان الوكيل. سيتم الرد في نفس الموضوع.
+
+### الخطوات (باستخدام SendGrid)
+
+1. قم بالتسجيل في **[sendgrid.com](https://sendgrid.com)**.
+2. أضف سجل MX لنطاقك حتى يتدفق البريد الوارد إلى SendGrid:
+   ```نص
+   MX yourcompany.com → mx.sendgrid.net (الأولوية 10)
+   ```
+3. افتح **الإعدادات ← التحليل الوارد**، انقر على **إضافة مضيف وURL**، وعيّن الوجهة على:
+
+   ```نص
+   https://your-app.example.com/_agent-native/integrations/email/webhook
+   ```
+
+4. ضبط متغيرات البيئة:
+   - `EMAIL_AGENT_ADDRESS` — العنوان الذي يتلقاه الوكيل على
+   - `SENDGRID_API_KEY` — مفتاح SendGrid API الخاص بك
+   - `EMAIL_INBOUND_WEBHOOK_SECRET` — سر توقيع Svix الاختياري إذا قمت بتكوين webhooks الموقع
+
+5. أرسل بريدًا إلكترونيًا إلى عنوان الوكيل.
+
+### نصائح
+
+- **CC الوكيل** لإحضاره إلى سلسلة رسائل. عندما يتم إرسال نسخة إلى الوكيل، فسوف يقوم بالرد على الكل حتى يرى سلسلة المحادثات بأكملها الرد.
+- **الترابط يعمل فقط** — يستخدم الوكيل رؤوس `Message-ID` / `In-Reply-To` / `References` القياسية، لذا تظل الردود في سلسلة الرسائل الصحيحة في أي عميل بريد إلكتروني.
+- **الهوية هي البريد الإلكتروني للمرسل.** إذا أرسل `alice@acme.com` بريدًا إلكترونيًا إلى الوكيل، فهذه _هي_ هويتها - لا يوجد رابط أو تدفق اشتراك.
+- **الردود المنسّقة** — يتم عرض تخفيض السعر في استجابة الوكيل على هيئة HTML في البريد الإلكتروني.
+- **المجالات المسموح بها** — تقييد من يمكنه إرسال بريد إلكتروني إلى الوكيل عن طريق تعيين `allowedDomains` في تكوين التكامل؛ يتم إسقاط الرسائل من النطاقات الأخرى.
+- **حد السعر** — 20 رسالة واردة في الساعة لكل مرسل.
+
+## إعداد واتساب {#whatsapp}
+
+### ما ستحتاج إليه
+
+- حساب مطور Meta (Facebook)
+- رقم هاتف يمكنك تخصيصه للبوت
+- حوالي 15 دقيقة (يحتوي إعداد Meta على معظم الخطوات)
+
+### الخطوات
+
+1. انتقل إلى **[Meta Developer Portal](https://developers.facebook.com/)**، وانقر على **إنشاء تطبيق**، واختر نوع **الأعمال**.
+2. أضف منتج **WhatsApp** إلى تطبيقك وقم بتكوين رقم هاتف لاستخدامه كمرسل.
+3. من صفحة إعداد WhatsApp، احصل على:
+   - **رمز الدخول** (الرمز المؤقت مناسب للاختبار؛ أنشئ رمزًا مميزًا دائمًا قبل بدء البث المباشر)
+   - **معرف رقم الهاتف**
+4. اختر أي سلسلة عشوائية لاستخدامها كرمز تحقق — ستدخل نفس القيمة في مكانين أدناه.
+5. في متغيرات بيئة تطبيقك، قم بتعيين:
+   - `WHATSAPP_ACCESS_TOKEN` — رمز الوصول الخاص بك
+   - `WHATSAPP_PHONE_NUMBER_ID` — معرف رقم الهاتف
+   - `WHATSAPP_VERIFY_TOKEN` — السلسلة العشوائية التي اخترتها
+6. بالرجوع إلى إعدادات WhatsApp الخاصة بـ Meta، افتح قسم webhook وقم بتعيين:
+
+   ```نص
+   رد الاتصال URL: https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
+   رمز التحقق: نفس السلسلة العشوائية التي قمت بتعيينها كـ WHATSAPP_VERIFY_TOKEN
+   ```
+
+   اشترك في الحقل `messages`.
+
+7. أرسل رسالة واتساب إلى رقم هاتف الروبوت.
+
+## استخدم Dispatch باعتباره البريد الوارد المركزي لوكيلك {#dispatch}
+
+إذا كنت تقوم بتشغيل العديد من تطبيقات الوكيل الأصلية (البريد والتقويم والتحليلات وما إلى ذلك)، فإن النمط الموصى به هو إعداد المراسلة على **[Dispatch](/docs/dispatch)** (راجع أيضًا [template reference](/docs/template-dispatch)) والسماح لها بتوجيه العمل إلى تطبيقات المجال الخاصة بك عبر [A2A](/docs/a2a-protocol).
+
+لماذا هذا لطيف:
+
+- **وكيل واحد، صندوق وارد واحد.** تتدفق جميع قنواتك (Slack، البريد الإلكتروني، Telegram، WhatsApp) إلى Dispatch. يمكنك إعداد عمليات التكامل مرة واحدة فقط.
+- **مندوبو Dispatch.** اسأل "تلخيص عمليات الاشتراك في الأسبوع الماضي" — تستدعي Dispatch وكيل التحليلات. اطلب "صياغة رد على أليس" — تتصل ديسباتش بوكيل البريد.
+- **النقرات، وليس التكوين.** تحتوي صفحة **الإعدادات → المراسلة** في Dispatch على أزرار اتصال لكل نظام أساسي مع حقول env-var المضمنة فيها.
+
+إذا لم تكن بحاجة إلى منسق، فيمكن لأي قالب منفرد توصيل الرسائل مباشرةً باستخدام env vars في هذه الصفحة.
+
+---
+
+## للمطورين {#for-developers}
+
+كل ما هو أدناه هو المرجع الفني. إذا كنت قد انتهيت من خطوات الإعداد المذكورة أعلاه، فيمكنك التوقف هنا إلا إذا كنت تقوم بتخصيص المكون الإضافي للتكامل أو إنشاء المحول الخاص بك.
+
+### كيفية العمل {#how-it-works}
+
+تستخدم منصة Inbound Platform webhooks نمط قائمة انتظار SQL عبر الأنظمة الأساسية بحيث تعمل على كل مضيف بدون خادم (Netlify وVercel وCloudflare Workers وFly وRender وNode) دون الاعتماد على عمليات API الخاصة بالتنفيذ في الخلفية الخاصة بالمنصة.
+
+1. المنصة `POST` إلى `/_agent-native/integrations/<platform>/webhook`. يتحقق المعالج من التوقيع، ويوزع الحمولة في `IncomingMessage`، و**يدرج صفًا في `integration_pending_tasks`** باستخدام `status='pending'`.
+2. يطلق المعالج إشارة "أطلق وانسى" `POST /_agent-native/integrations/process-task` ويعيد `200` على الفور، داخل Slack لمدة 3 ثوانٍ في SLA.
+3. تعمل نقطة نهاية المعالج في **تنفيذ وظيفة جديدة** بميزانية المهلة الكاملة الخاصة بها. فهو يطالب بالمهمة ذريًا (`pending` → `processing` عبر `claimPendingTask`)، ويقوم بتشغيل حلقة الوكيل، وينشر الرد من خلال المحول، ويضع علامة على المهمة `completed`.
+4. تقوم مهمة إعادة المحاولة المتكررة (`startPendingTasksRetryJob`، كل 60 ثانية) بمسح المهام العالقة في `pending` >90 ثانية أو `processing` > 5 دقائق وتعيد تشغيل المعالج. تم تحديد 3 محاولات، ثم تم وضع علامة `failed`.
+
+```an-diagram title="Inbound webhook lifecycle" summary="The webhook only verifies, enqueues, and returns 200. A fresh function execution drains the queue and runs the agent loop, with a 60s retry job as the safety net."
+{
+  "html": "<div class=\"msg-flow\"><div class=\"msg-row\"><div class=\"diagram-node\">Platform<br><small class=\"diagram-muted\">Slack · email · etc.</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><strong>/webhook</strong><br><small class=\"diagram-muted\">verify signature + parse</small><br><span class=\"diagram-pill\">INSERT pending task</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">return 200</div></div><div class=\"msg-fire\"><span class=\"diagram-muted\">fire-and-forget</span> <span class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</span></div><div class=\"msg-row\"><div class=\"diagram-box\" data-rough><strong>/process-task</strong><br><small class=\"diagram-muted\">fresh execution · own timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">claim</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">agent loop</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">adapter.sendResponse</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">completed</div></div><div class=\"diagram-panel msg-retry\" data-rough><span class=\"diagram-pill warn\">every 60s</span> <span class=\"diagram-muted\">retry job sweeps stuck tasks (pending &gt;90s · processing &gt;5min) and re-fires /process-task &mdash; capped at 3 attempts, then <strong>failed</strong></span></div></div>",
+  "css": ".msg-flow{display:flex;flex-direction:column;gap:12px}.msg-flow .msg-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.msg-flow .msg-fire{display:flex;align-items:center;gap:8px;padding-inline-start:12px}.msg-flow .msg-retry{display:flex;align-items:center;gap:8px;flex-wrap:wrap}"
+}
+```
+
+توجد المحادثات الواردة والصادرة في نفس سلسلة رسائل SQL، لذا يمكنك متابعة رسالة مباشرة Slack من الويب UI أو العكس.
+
+```an-api
+{
+  "method": "POST",
+  "path": "/_agent-native/integrations/slack/webhook",
+  "summary": "Slack Events API inbound webhook",
+  "description": "Receives Slack events (DMs and channel `app_mention`s). Verifies the request signature, parses the payload into an `IncomingMessage`, inserts a `pending` row into `integration_pending_tasks`, fires the fresh-execution processor, and returns **200 immediately** — well inside Slack's 3-second SLA. The same route shape exists per platform under `/_agent-native/integrations/<platform>/webhook`.",
+  "auth": "HMAC-SHA256 of the raw body using `SLACK_SIGNING_SECRET`, checked against the `X-Slack-Signature` header. In production also gated by `SLACK_ALLOWED_TEAM_IDS` / `SLACK_ALLOWED_API_APP_IDS`.",
+  "params": [
+    { "name": "X-Slack-Signature", "in": "header", "type": "string", "required": true, "description": "Slack request signature, verified before any processing." },
+    { "name": "X-Slack-Request-Timestamp", "in": "header", "type": "string", "required": true, "description": "Timestamp used in the signature base string." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"type\": \"event_callback\",\n  \"team_id\": \"T0123\",\n  \"api_app_id\": \"A0123\",\n  \"event\": {\n    \"type\": \"message\",\n    \"channel_type\": \"im\",\n    \"user\": \"U0123\",\n    \"text\": \"summarize last week's signups\"\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "Acknowledged immediately. The agent loop runs in the separate /process-task execution. The first time a Request URL is saved, Slack POSTs a `url_verification` challenge and the adapter replies with the `challenge` value automatically.", "example": "{ \"ok\": true }" },
+    { "status": "401", "description": "Signature verification failed, or the team/app id is not in the production allowlist." }
+  ]
+}
+```
+
+#### لماذا هذا النمط (وليس الاختصارات الأصلية للمنصة) {#why-this-pattern}
+
+تتجمد الوظائف بدون خادم لحظة إرسال الاستجابة. أي شيء لا يزال قيد التشغيل - بما في ذلك وعد "أطلق وانسى" أو مكالمة LLM المؤجلة أو أداة أثناء الطيران - يتم إيقافه في منتصف التنفيذ. الطريقة الوحيدة لإبقاء حلقة الوكيل على قيد الحياة هي بدء تنفيذ وظيفة **جديدة** لها، وهو ما يفعله `/process-task` POST الذي يتم تشغيله ذاتيًا.
+
+هل يستخدم NOT أيًا من هذه البدائل:
+
+- **وظائف خلفية Netlify** — Netlify فقط، وتتطلب لاحقة اسم ملف `-background.ts`، وتتوقف عند كل مضيف آخر.
+- **Cloudflare `event.waitUntil()`** — عمال CF فقط، غير محمولين.
+- **Vercel `after()` / Fluid** — Vercel فقط، خلف أوقات تشغيل محددة.
+- **وعود إطلاق النار والنسيان العارية بعد `return`** — تُقتل بصمت عندما تتجمد الوظيفة؛ لا يوجد خطأ في السجلات، ولن يحصل المستخدم على رد أبدًا.
+
+إن مجموعة SQL-queue + self-webhook + إعادة محاولة المهمة هي الشيء الوحيد الذي يعمل بشكل مماثل على كل مضيف مدعوم. مهمة إعادة المحاولة هي شبكة الأمان - لا تفترض أبدًا أن الإرسال الأولي قد تم مسحه قبل تجميد الوظيفة.
+
+### المكون الإضافي لعمليات التكامل {#plugin}
+
+يتم تثبيت المكون الإضافي تلقائيًا في حالة عدم وجود إصدار مخصص. للتخصيص، قم بإنشاء:
+
+```ts
+// server/plugins/integrations.ts
+import { createIntegrationsPlugin } from "@agent-native/core/server";
+import { scriptRegistry } from "../../agent.config";
+
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+});
+```
+
+تعتمد الأنظمة الأساسية النشطة على نوع env vars الذي تم تعيينه. يسجل المكون الإضافي مسارات خطاف الويب لكل مسار ضمن `/_agent-native/integrations/`.
+
+### الخطاف التلقائي على الويب URL {#webhook-urls}
+
+```text
+/_agent-native/integrations/slack/webhook
+/_agent-native/integrations/telegram/webhook
+/_agent-native/integrations/whatsapp/webhook
+/_agent-native/integrations/email/webhook
+```
+
+يكشف Telegram أيضًا عن نقطة نهاية الإعداد لمرة واحدة:
+
+```text
+POST /_agent-native/integrations/telegram/setup
+```
+
+### متغيرات البيئة {#env-vars}
+
+| المنصة            | مطلوب                                                                              | اختياري                                               |
+| ----------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Slack             | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                          | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
+| تيليجرام          | `TELEGRAM_BOT_TOKEN`                                                               | —                                                     |
+| البريد الإلكتروني | `EMAIL_AGENT_ADDRESS`، بالإضافة إلى واحد من `RESEND_API_KEY` أو `SENDGRID_API_KEY` | `EMAIL_INBOUND_WEBHOOK_SECRET`                        |
+| واتساب            | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`       | —                                                     |
+
+جميع بيانات الاعتماد موجودة في env vars - وليس قاعدة البيانات أبدًا، ولا كود المصدر أبدًا. استخدم إعدادات الشريط الجانبي UI أو لوحة البيئة الخاصة بموفر الاستضافة.
+
+### الترابط والهوية {#threading-and-identity}
+
+يتم تعيين كل محادثة خارجية لسلسلة محادثات مستمرة في قاعدة بيانات الوكيل الأصلية:
+
+- **Slack DM** → موضوع واحد لكل مستخدم Slack.
+- **@إشارة قناة Slack** → موضوع واحد لكل قناة.
+- **دردشة تيليجرام** → موضوع واحد لكل دردشة تيليجرام.
+- **محادثة WhatsApp** → موضوع واحد لكل رقم WhatsApp.
+- **البريد الإلكتروني** → سلسلة الرسائل مشتقة من رؤوس `Message-ID` / `In-Reply-To` / `References`.
+
+تظهر المواضيع الخارجية في الويب UI جنبًا إلى جنب مع المواضيع التي تم إنشاؤها على الويب، والتي تم وضع علامة عليها باستخدام نظامها الأساسي المصدر. تحليل الهوية: عندما يطابق مستخدم Slack/البريد الإلكتروني مستخدمًا مسجلاً (عادةً عن طريق البريد الإلكتروني)، يتم ربطه بهذا الحساب.
+
+### الأمان {#security}
+
+يتم التحقق من توقيع كل خطاف ويب وارد قبل المعالجة:
+
+- **Slack** — HMAC-SHA256 للجسم باستخدام `SLACK_SIGNING_SECRET`، تم فحصه مقابل رأس `X-Slack-Signature`. في المرة الأولى التي تقوم فيها بحفظ طلب URL في لوحة اشتراكات الأحداث الخاصة بـ Slack، تقوم Slack بنشر تحدي `url_verification` له؛ يكتشف محول إطار العمل ذلك ويرد بقيمة `challenge` تلقائيًا، لذلك يتحول URL إلى اللون الأخضر في Slack دون أي عمل إضافي من جانبك.
+- **Telegram** — يتم تعيين الرمز السري عند تسجيل خطاف الويب.
+- **WhatsApp** — اختبار التحقق من Meta (باستخدام `WHATSAPP_VERIFY_TOKEN`) بالإضافة إلى توقيع الحمولة.
+- **البريد الإلكتروني** — التحقق من التوقيع بنمط Svix عند تعيين `EMAIL_INBOUND_WEBHOOK_SECRET` (يستخدم كل من Resend وSendGrid هذا التنسيق). إذا لم يتم تعيين السر، فسيتم قبول خطاف الويب ولكن يتم تسجيل تحذير.
+
+يفرض محول البريد الإلكتروني أيضًا ما يلي:
+
+- **المجالات المسموح بها** — مصفوفة `allowedDomains` اختيارية في صف `integration_configs` الخاص بالتكامل؛ يتم إسقاط المرسلين من خارج القائمة.
+- **حد السعر** — حد معدل SQL المدعوم بقائمة الانتظار يبلغ 20 رسالة واردة لكل مرسل في الساعة.
+
+### الإرسال الاستباقي {#proactive-sends}
+
+يمكن للوكيل إرسال رسائل من تلقاء نفسه (الإعلامات والتذكيرات والملخصات المجدولة) عن طريق استدعاء إجراء `send-platform-message` باستخدام حقل `platform` `"slack"` أو `"telegram"` أو `"whatsapp"` أو `"email"`. الإجراء موجود في حزمة Dispatch في `packages/dispatch/src/actions/send-platform-message.ts` ويمكنك نسخه/تكييفه مع أي قالب.
+
+### المحولات المخصصة {#custom-adapters}
+
+لإضافة منصة مراسلة جديدة، قم بتنفيذ واجهة `PlatformAdapter`:
+
+```ts
+import type { H3Event } from "h3";
+import type {
+  PlatformAdapter,
+  IncomingMessage,
+  OutgoingMessage,
+} from "@agent-native/core/server";
+import type { EnvKeyConfig } from "@agent-native/core/server";
+
+const myAdapter: PlatformAdapter = {
+  platform: "discord",
+  label: "Discord",
+
+  // Env keys this adapter needs (rendered in the settings UI)
+  getRequiredEnvKeys(): EnvKeyConfig[] {
+    return [
+      { key: "DISCORD_BOT_TOKEN", label: "Discord Bot Token", required: true },
+    ];
+  },
+
+  // Handle platform-specific verification challenges (e.g. Slack's
+  // url_verification). Return { handled: true, response } to short-circuit.
+  async handleVerification(event: H3Event) {
+    return { handled: false };
+  },
+
+  // Validate the webhook request signature
+  async verifyWebhook(event: H3Event): Promise<boolean> {
+    // Validate signature headers; return true if authentic
+    return true;
+  },
+
+  // Parse the webhook payload into a normalized IncomingMessage.
+  // Return null to silently ignore the event (bot messages, edits, etc.).
+  async parseIncomingMessage(event: H3Event): Promise<IncomingMessage | null> {
+    return {
+      platform: "discord",
+      externalThreadId: "channel-or-thread-id",
+      text: "the user's message",
+      senderId: "discord-user-id",
+      platformContext: { channelId: "channel-id" },
+      timestamp: Date.now(),
+    };
+  },
+
+  // Format plain agent text into a platform-appropriate OutgoingMessage.
+  // opts.threadDeepLinkUrl, when provided, is a URL back to the originating
+  // thread in the dispatch UI — render it as a button (Slack) or inline link.
+  formatAgentResponse(
+    text: string,
+    opts?: { threadDeepLinkUrl?: string },
+  ): OutgoingMessage {
+    return { text, platformContext: {} };
+  },
+
+  // Post the agent's response back to the platform
+  async sendResponse(
+    message: OutgoingMessage,
+    context: IncomingMessage,
+  ): Promise<void> {
+    // Call the platform's API, using context.platformContext for routing
+  },
+
+  // Return current connection/configuration status for the settings UI.
+  // baseUrl is the app's public URL, used for status checks that need it.
+  async getStatus(baseUrl?: string) {
+    return {
+      platform: "discord",
+      label: "Discord",
+      enabled: true,
+      configured: !!process.env.DISCORD_BOT_TOKEN,
+    };
+  },
+};
+```
+
+سجله في البرنامج المساعد للتكامل الخاص بك:
+
+```ts
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  adapters: [myAdapter],
+});
+```
+
+التطبيقات المرجعية موجودة في `packages/core/src/integrations/adapters/` (`slack.ts`، `telegram.ts`، `whatsapp.ts`، `email.ts`) — محول البريد الإلكتروني هو المثال الأكثر اكتمالا، بما في ذلك التحقق من التوقيع، والترابط، وتحديد المعدل، وعرض HTML.
+
+### الموثوقية عبر استمرارية Dispatch + A2A {#reliability}
+
+عندما يقوم [Dispatch](/docs/dispatch) بتفويض طلب إلى تطبيق آخر عبر [A2A](/docs/a2a-protocol#continuations)، يضمن تدفق استمرار الاسترداد حصول المستخدم على رد Slack/البريد الإلكتروني حتى إذا تعطل وكيل المصب في منتصف التنفيذ. تظل مهمة webhook الأصلية في `processing` حتى يتم حل المتابعة أو تشير عملية المسح لإعادة المحاولة إلى أنها عالقة؛ وفي كلتا الحالتين، يحصل موضوع المنصة على رد نهائي بدلاً من الصمت.
+
+يعني هذا أن مساحة العمل متعددة التطبيقات التي تقدمها Dispatch أكثر مرونة من قالب واحد متصل بالمراسلة مباشرة - حيث تؤدي حالات الفشل في أي تطبيق واحد إلى ظهور رسالة خطأ بسيطة بدلاً من إسقاط الرد. راجع [A2A continuations](/docs/a2a-protocol#continuations) للاطلاع على القصة الكاملة لضمان التسليم.
+
+### المزالق الشائعة {#pitfalls}
+
+- **لا تقرأ نص الطلب مرتين.** يتم استهلاك دفق نص h3 v2 مرة واحدة: إذا اتصلت بـ `readBody(event)` بعد أن قام إطار العمل بالفعل بتحليل `event.node.req.body` (أو العكس)، فإن القراءة الثانية تعلق الطلب إلى أجل غير مسمى. يظهر هذا في أغلب الأحيان مع Resend وSendGrid - كلاهما دفق الحمولة الواردة ولا يتم حل القراءة المتدلية أبدًا، وتنتهي مهلة النظام الأساسي، وتتم إعادة محاولة خطاف الويب حتى يتم التخلص منه. إذا قمت بلف معالج خطاف الويب الخاص بإطار العمل في برنامجك الوسيط، فقم بتمرير `IncomingMessage` الذي تم تحليله بالفعل عبر خيار `incoming` بدلاً من السماح للمعالج بإعادة التحليل.
+- **لا تقم بتشغيل حلقات الوكيل داخل معالج webhook.** يجب أن يقوم المعالج بوضعه في قائمة الانتظار والعودة — يتم تشغيل حلقة الوكيل في التنفيذ الجديد للمعالج. ويضمن وضعه في السطر أن يؤدي التجميد بدون خادم إلى إنهاء التشغيل. علاوة على ذلك، فإن عمليات تكامل البوابة العامة (مثل Netlify أو Vercel) تفرض حدودًا صارمة لمهلة HTTP (على سبيل المثال، حد طلب Netlify البالغ 10 ثوانٍ). نظرًا لأن تشغيل الوكيل والأدوات غالبًا ما تستغرق وقتًا أطول من هذه النافذة، فإن محاولة تشغيل الحلقة بشكل متزامن داخل طلب خطاف الويب سوف يتسبب في قيام البوابة بإنهاء الاتصال، مما يؤدي إلى إحباط التنفيذ وإسقاط الردود. يعد نمط قائمة الانتظار HMAC ذاتي الخطاف `/process-task` هو الطريقة الوحيدة لتلبية حدود البوابة أثناء تنفيذ حلقة الوكيل الكاملة بأمان.
+- **لا تعتمد على ذاكرة الحذف أثناء عمليات التشغيل الباردة.** يوجد مفتاح الحذف في الفهرس الفريد SQL `(platform, external_event_key)`، وليس في خريطة قيد المعالجة. إذا قمت باستبدال قائمة الانتظار، فاحتفظ بعملية الحذف على مستوى SQL أو ستؤدي عمليات إعادة المحاولة Slack المكررة إلى تشغيل الوكيل المكرر.
+- **حافظ على إمكانية الوصول إلى خطاف الويب الذاتي URL.** تم إنشاء المعالج URL من `APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL`، ويعود إلى رؤوس الطلبات الواردة. عند نشر المعاينة باستخدام أسماء المضيفين المعاد كتابتها، قم بتعيين أحد هذه الأسماء بشكل صريح وإلا سيصل الإرسال إلى 404.
+
+### انظر أيضًا {#see-also}
+
+- [Dispatch](/docs/dispatch) — نظرة عامة على مفهوم استخدام البريد الوارد المركزي عبر التطبيقات
+- [Dispatch template reference](/docs/template-dispatch) — البريد الوارد المركزي الموصى به لمساحات العمل متعددة التطبيقات
+- [A2A Protocol](/docs/a2a-protocol) — كيفية عمل مندوبي Dispatch إلى الوكلاء الآخرين، بما في ذلك استمرار الاسترداد
+- [Agent Mentions](/docs/agent-mentions) — وكلاء الإشارة إلى `@` داخل دردشة الويب

package/docs/content/locales/ar-SA/migration-workbench.md

@@ -0,0 +1,33 @@
+---
+title: "الترحيل إلى Agent-Native (/الترحيل)"
+description: "الترحيل هو هدف مضمن/ترحيل في مساحة عمل Agent-Native Code - وليس تطبيقًا منفصلاً. راجع رمز Agent-Native UI للحصول على الدليل الكامل."
+---
+
+# الترحيل إلى Agent-Native (/الترحيل)
+
+الترحيل **ليس منتجًا أو قالبًا منفصلاً** — فهو مضمن
+هدف `/migrate` داخل مساحة عمل [Agent-Native Code](/docs/code-agents-ui).
+يتم تشغيله كجلسة تعليمات برمجية عادية يمكنك استئنافها والإرفاق بها وفحصها وإيقافها.
+
+```an-diagram title="/migrate is a Code session, not a separate app" summary="A path, URL, or description goes in; the run shares the same store, transcript, and controls as every other Code session, and can emit a portable dossier."
+{
+  "html": "<div class=\"diagram-migrate\"><div class=\"diagram-col\"><div class=\"diagram-pill\">./local-app</div><div class=\"diagram-pill\">https://example.com</div><div class=\"diagram-pill\">--describe \\\"...\\\"</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">/migrate goal</span><small class=\"diagram-muted\">same store · transcript · run controls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>Migrated app</div><div class=\"diagram-pill ok\">--emit dossier</div></div></div>",
+  "css": ".diagram-migrate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-migrate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-migrate .diagram-arrow{font-size:22px;line-height:1}.diagram-migrate .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+```bash
+npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app
+npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site plus dashboard"
+npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app   # shortcut into the same goal
+```
+
+الدليل الكامل — أشكال الإدخال (المسار / URL / الوصف)، ملفات `--emit`،
+وضع التخطيط مقابل الوضع التلقائي، وعناصر التحكم في التشغيل، وبيانات الاعتماد، والروابط العميقة لسطح المكتب، و
+صادرات الحزمة `@agent-native/migrate` — موجودة في
+[Agent-Native Code UI → Migrating to Agent-Native](/docs/code-agents-ui#migrate).
+
+> [!NOTE]
+> تمت إزالة تطبيق تفاصيل `migration` القديم المخفي. استخدم الكود
+> ، أو علامة التبويب Desktop Code، أو الملف المنبعث كالملف المدعوم
+> الأسطح.