@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ar-SA/recurring-jobs.md

@@ -0,0 +1,142 @@
+---
+title: "الوظائف المتكررة"
+description: "تعمل المطالبات المجدولة بواسطة Cron على تشغيل الوكيل من تلقاء نفسه - الملخصات اليومية والتقارير الأسبوعية والاستقصاء كل ساعة."
+---
+
+# الوظائف المتكررة
+
+**المهمة المتكررة** هي مطالبة يتم تشغيلها وفقًا لجدول cron. إنها الطريقة التي يقوم بها الوكيل بالأشياء من تلقاء نفسه: "كل صباح في الساعة 7، قم بتلخيص رسائل البريد الإلكتروني الليلية الخاصة بي،" "كل يوم اثنين أنشر أرقام الاشتراك الأسبوع الماضي في Slack،" "كل ساعة ابحث عن المسودات القديمة وقم بحذفها."
+
+يتم تشغيل المهام المتكررة على مدار الساعة. للتفاعل مع _events_ (تم إنشاء الحجز، واستلام بريد إلكتروني) - نفس تنسيق ملف `jobs/` بالإضافة إلى الشروط - راجع [Automations](/docs/automations).
+
+توجد الوظائف في [workspace](/docs/workspace) في `jobs/<name>.md` - مجرد ملف Markdown مع المادة الأمامية YAML. لا يوجد تسجيل، لا الأسلاك. قم بإسقاط الملف وسيلتقطه إطار العمل.
+
+## ملف الوظيفة {#job-file}
+
+```an-annotated-code title="jobs/morning-digest.md"
+{
+  "filename": "jobs/morning-digest.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"0 7 * * *\"\nenabled: true\nrunAs: creator\n---\n\n# Morning digest\n\nSummarize the emails received overnight. Group by sender domain.\nPin the top 3 threads that look like they need a reply today to the\n\"Needs reply\" label. Draft replies for any that are obvious.",
+  "annotations": [
+    { "lines": "2", "label": "When", "note": "Standard 5-field cron — `0 7 * * *` is every day at 07:00." },
+    { "lines": "3", "label": "Pause switch", "note": "Flip to `false` to stop the job without deleting it." },
+    { "lines": "4", "label": "Identity", "note": "`creator` runs with the owner's identity and `ANTHROPIC_API_KEY`; `shared` uses the org's key." },
+    { "lines": "7-12", "label": "The prompt", "note": "The body is just a prompt — the agent runs it at each firing with all its normal tools and workspace context." }
+  ]
+}
+```
+
+هذا كل شيء. الجسم عبارة عن موجه يقوم العميل بتشغيله عند كل إطلاق مجدول. يتمتع الوكيل بحق الوصول إلى نفس الأدوات وسياق مساحة العمل الموجود في الدردشة التفاعلية — actions، skills، الذاكرة، خوادم MCP المتصلة، الوكلاء الفرعيون.
+
+## المهمه الاماميه {#frontmatter}
+
+| الحقل        | اكتب                          | الافتراضي   | الوصف                                                                                                   |
+| ------------ | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
+| `schedule`   | تعبير كرون                    | _(مطلوب)_   | كرون قياسي ذو 5 حقول. `"0 7 * * *"` = كل يوم الساعة 07:00؛ `"0 */4 * * *"` = كل 4 ساعات.                |
+| `enabled`    | منطقية                        | `true`      | انتقل إلى `false` للإيقاف مؤقتًا دون حذف المهمة.                                                        |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"` | يتم تشغيل `"creator"` باستخدام هوية مالك الوظيفة و`ANTHROPIC_API_KEY`. يستخدم `"shared"` مفتاح المؤسسة. |
+| `createdBy`  | البريد الإلكتروني             | _(تلقائي)_  | يتم نشره عند إنشاء الوظيفة من خلال مساحة العمل UI أو بواسطة الوكيل.                                     |
+| `orgId`      | سلسلة                         | _(تلقائي)_  | نطاق المؤسسة؛ موروثة من مؤسسة المنشئ النشطة.                                                            |
+| `lastRun`    | الطابع الزمني ISO             | _(مُدار)_   | يكتبه المجدول بعد كل تشغيل.                                                                             |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(مُدار)_   | أحدث النتائج.                                                                                           |
+| `lastError`  | سلسلة                         | _(مُدار)_   | رسالة خطأ في حالة فشل التشغيل الأخير.                                                                   |
+| `nextRun`    | الطابع الزمني ISO             | _(مُدار)_   | محسوب من `schedule`؛ يستخدمه المجدول لتحديد موعد الإطلاق التالي.                                        |
+
+تتم كتابة الحقول `last*` و`nextRun` بواسطة المجدول. يمكنك قراءتها لرؤية السجل، لكن لا تقم بتحريرها يدويًا - سيتم استبدالها في المرة التالية.
+
+## بناء جملة كرون {#cron}
+
+كرون قياسي ذو 5 حقول (الدقيقة، الساعة، يوم من الشهر، شهر، يوم من الأسبوع):
+
+| كرون           | المعنى                    |
+| -------------- | ------------------------- |
+| `*/5 * * * *`  | كل 5 دقائق                |
+| `0 * * * *`    | كل ساعة على مدار الساعة   |
+| `0 */4 * * *`  | كل 4 ساعات                |
+| `0 7 * * *`    | كل يوم الساعة 07:00       |
+| `0 9 * * 1`    | كل يوم اثنين الساعة 09:00 |
+| `0 17 * * 1-5` | أيام الأسبوع الساعة 17:00 |
+| `0 0 1 * *`    | اليوم الأول من كل شهر     |
+
+يتضمن إطار العمل أدوات مساعدة cron (`isValidCron()` و`describeCron()`) للتحقق من صحة وعرض سلاسل cron، المستخدمة داخليًا بواسطة طبقات الموارد والمجدولة.
+
+## إنشاء وظيفة {#creating}
+
+### من علامة التبويب "مساحة العمل"
+
+`+` → **المهمة المجدولة** في لوحة مساحة العمل. املأ المطالبة والجدول الزمني. يتم الحفظ باسم `jobs/<slug>.md` ويبدأ التشغيل عند علامة الاختيار المطابقة التالية.
+
+### من خلال سؤال الوكيل
+
+> "قم بإنشاء مهمة مجدولة تلخص رسائل البريد الإلكتروني غير المقروءة كل صباح الساعة 7."
+
+يقوم الوكيل بكتابة الملف نيابةً عنك.
+
+### باليد
+
+أسقط ملف Markdown في `jobs/` عبر مورد إطار العمل APIs:
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## كيفية تشغيل المجدول {#how-scheduler-runs}
+
+المجدول هو مكون إضافي لإطار العمل (روتين `processRecurringJobs()` الداخلي) يتم تشغيله أثناء العملية: يتم تنشيط `setInterval` كل 60 ثانية (مع تأخير بدء التشغيل لمدة 10 ثوانٍ) داخل المكون الإضافي لدردشة الوكيل، أينما كان الخادم قيد التشغيل.
+
+```an-diagram title="One scheduler tick" summary="Every 60s the scheduler finds due jobs, runs each as a fresh agent thread, and writes the outcome back to the job file."
+{
+  "html": "<div class=\"sched\"><div class=\"diagram-box accent\"><code>setInterval</code> &bull; 60s &#8635;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">1 &middot; scan</span><small class=\"diagram-muted\">list every enabled <code>jobs/*.md</code> across all owners</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">2 &middot; due?</span><small class=\"diagram-muted\">compare <code>nextRun</code> to now</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">3 &middot; run</span><small class=\"diagram-muted\">fresh agent thread, job body as the user message &mdash; actions, SQL, A2A, email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">4 &middot; record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code>, recompute <code>nextRun</code></small></div></div>",
+  "css": ".sched{display:flex;flex-direction:column;gap:6px;max-width:520px}.sched .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.sched .diagram-box{align-self:flex-start}.sched .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+```an-callout
+{ "tone": "risk", "body": "**Scale-to-zero caveat.** The scheduler is in-process, so on serverless hosts jobs only fire while an instance is warm. If reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS)." }
+```
+
+## تصحيح أخطاء المهمة {#debugging}
+
+- افتح `jobs/<name>.md` في مساحة العمل - تعرض المادة الأمامية `lastRun`، `lastStatus`، `lastError`، `nextRun`.
+- **اختبره دون انتظار:** لا توجد أداة للقوة. لممارسة نفس العمل عند الطلب، قم إما بلصق مطالبة الوظيفة في دردشة الوكيل والسماح لها بالعمل هناك، أو قم بتعيين الجدول مؤقتًا على الدقيقة التالية حتى يلتقطها المجدول في العلامة التالية (ثم قم باستعادة cron الحقيقي).
+- **إيقاف مؤقت:** اقلب `enabled: false`. يبقى الملف في مكانه، ويتوقف عن التشغيل.
+
+## أداة الوكيل {#agent-tool}
+
+يتم تسجيل أداة `manage-jobs` واحدة في كل قالب. تحدد المعلمة `action` العملية:
+
+| الإجراء  | المعلمات                                                       | الغرض                                                           |
+| -------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
+| `create` | `name`، `schedule`، `instructions` (مطلوب)؛ `scope`، `runAs`   | إنشاء مهمة متكررة جديدة                                         |
+| `list`   | `scope` (`personal`، `shared`، أو الكل)                        | سرد كافة المهام ذات الحالة (جدول، ممكّن، التشغيل الأخير/التالي) |
+| `update` | `name` (مطلوب)؛ `schedule`، `instructions`، `enabled`، `runAs` | تحرير مهمة موجودة                                               |
+| `delete` | `name` (مطلوب)                                                 | حذف مهمة - قم دائمًا بالتأكيد مع المستخدم أولاً                 |
+
+**النطاق الشخصي مقابل النطاق المشترك.** توجد كل وظيفة إما في النطاق الشخصي (يتم تشغيله ويكون مرئيًا للمنشئ فقط) أو النطاق المشترك/المؤسسي (يتم تشغيله نيابة عن المنشئ ولكنه مرئي لأعضاء المؤسسة). تتحكم المعلمات `scope` و`runAs` في ذلك في وقت الإنشاء. يمكن لمسؤولي المؤسسة تحديث أو حذف أي مهمة مشتركة؛ يمكن للأعضاء غير الإداريين إدارة أعضاءهم فقط.
+
+## تختلف عن حزمة الجدولة {#vs-scheduling-package}
+
+لا تخلط بين المهام المتكررة و`@agent-native/scheduling`:
+
+- **المهام المتكررة (هذه الصفحة)** — _prompts_ المجدولة لـ cron التي يقوم الوكيل بتشغيلها في الخلفية. مستوى الإطار. يعيش في مساحة العمل. يعمل على أي تطبيق أصلي للوكيل.
+- **`@agent-native/scheduling`** — حزمة نطاق قابلة لإعادة الاستخدام لإنشاء ميزات التقويم/الحجز (أنواع الأحداث، ونوافذ التوفر، والحجوزات). لتشغيل قالب `calendar` وأسطح الجدولة المخصصة.
+
+المهام المتكررة هي "كيف أجعل الوكيل يتصرف من تلقاء نفسه؟" حزمة الجدولة هي "كيف يمكنني إنشاء تطبيق تقويم؟" مخاوف مختلفة.
+
+## ما هي الخطوة التالية
+
+- [**Automations**](/docs/automations) - إضافة مشغلات وشروط الأحداث إلى تنسيق `jobs/` نفسه
+- [**Workspace**](/docs/workspace) — حيث توجد الوظائف جنبًا إلى جنب مع skills والذاكرة والوكلاء المخصصين
+- [**Actions**](/docs/actions) — الأدوات التي تتطلبها الوظيفة
+- [**Agent Teams**](/docs/agent-teams) — غالبًا ما تنتج الوظائف وكلاء فرعيين للقيام بأعمال موازية

package/corpus/core/docs/content/locales/ar-SA/routing.md

@@ -0,0 +1,79 @@
+---
+title: "التوجيه"
+description: "التوجيه المستند إلى الملفات لتطبيقات الوكيل الأصلية باستخدام React Router v7 - الصفحات والمعلمات الديناميكية والتنقل."
+---
+
+# التوجيه
+
+تستخدم تطبيقات الوكيل الأصلية **React Router v7** مع التوجيه المستند إلى الملف عبر `flatRoutes()` من `@react-router/fs-routes`. كل ملف في `app/routes/` يصبح URL. تستخدم القوالب اصطلاح التدوين النقطي — حيث تفصل النقاط مقاطع URL داخل اسم ملف واحد.
+
+## التوجيه المستند إلى الملف {#file-based-routing}
+
+### ملف → تعيين URL
+
+| ملف                   | URL                | ملاحظات                                 |
+| --------------------- | ------------------ | --------------------------------------- |
+| `_index.tsx`          | `/`                | فهرس المسار                             |
+| `settings.tsx`        | `/settings`        | صفحة بسيطة                              |
+| `inbox.$threadId.tsx` | `/inbox/:threadId` | النقطة = `/`، `$` = المعلمة الديناميكية |
+| `_app.tsx`            | (لا يوجد مقطع URL) | تخطيط بدون مسار — بادئة بـ `_`          |
+| `inbox/route.tsx`     | `/inbox`           | نموذج المجلد — `route.tsx` هو الفهرس    |
+
+بادئة مقطع بـ `$` لمعلمة ديناميكية. البادئة بـ `_` لجعلها مسار تخطيط بلا مسار (لا يوجد مقطع URL). تستخدم القوالب `flatRoutes()` — ملف التدوين النقطي أعلاه هو ملف أساسي؛ يعمل أيضًا نموذج المجلد المتداخل `inbox/route.tsx`.
+
+```an-diagram title="Pathless layout wraps the pages" summary="A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."
+{
+"html": "<div class=\"diagram-layout\" data-rough><div class=\"diagram-shell\"><span class=\"diagram-pill accent\">_app.tsx</span><small class=\"diagram-muted\">pathless layout · persistent shell + agent sidebar</small><div class=\"diagram-outlet\" data-rough><small class=\"diagram-muted\">&lt;Outlet/&gt; — the matched page</small><div class=\"diagram-row\"><span class=\"diagram-pill\">_index.tsx &rarr; /</span><span class=\"diagram-pill\">settings.tsx &rarr; /settings</span><span class=\"diagram-pill\">inbox.$threadId.tsx &rarr; /inbox/:threadId</span></div></div></div></div>",
+"css": ".diagram-layout .diagram-shell{display:flex;flex-direction:column;gap:8px;padding:16px}.diagram-layout .diagram-outlet{display:flex;flex-direction:column;gap:8px;padding:14px;margin-top:6px}.diagram-layout .diagram-row{display:flex;flex-wrap:wrap;gap:8px;margin-top:4px}"
+}
+
+```
+
+## إضافة صفحة جديدة {#adding-a-page}
+
+قم بإنشاء الملف وتصدير المكون الافتراضي:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+هذا كل شيء — يقوم جهاز التوجيه React باستلامها تلقائيًا، دون الحاجة إلى التسجيل.
+
+## المعاملات الديناميكية {#dynamic-params}
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+## الملاحة {#navigation}
+
+استخدم `<Link>` للتنقل من جانب العميل و`useNavigate()` للتنقل البرمجي:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+## ما هي الخطوة التالية
+
+- [**Client**](/docs/client) — أدوات مساعدة وربط المتصفح الأصلي للوكيل
+- [**Server**](/docs/server) — مسارات الخادم المستندة إلى الملفات ومساحة الاسم `/_agent-native/`

package/corpus/core/docs/content/locales/ar-SA/sandbox-adapters.md

@@ -0,0 +1,227 @@
+---
+title: "المحولات"
+description: "طبقتا محول إطار العمل: تقوم محولات وضع الحماية بتبديل الواجهة الخلفية التي تقوم بتشغيل أداة تشغيل التعليمات البرمجية الخاصة بالوكيل، وتمنح محولات CLI الوكيل وصولاً منظمًا إلى أدوات سطر الأوامر."
+search: "المحولات، محول وضع الحماية، محول cli، رمز التشغيل، SandboxAdapter، CliAdapter، ShellCliAdapter، عداء متين، وضع الحماية عن بعد، حافة عملية بدون خادم"
+---
+
+# المحولات
+
+> **من هو:** المؤلفون المضيفون الذين يقومون بتمديد وقت التشغيل. نادرًا ما يكون مطورو التطبيقات
+> إلى هذا — فالإعدادات الافتراضية تعمل خارج الصندوق.
+
+تحتوي Agent-Native على درزتي محول تعملان على إزالة المشكلة خلف فتحة ضيقة،
+واجهة قابلة للتبديل:
+
+- **محولات Sandbox** تقوم بتبديل الواجهة الخلفية التي تقوم بتشغيل أداة `run-code` الخاصة بالوكيل —
+  عملية فرعية محلية بشكل افتراضي، أو مشغل Docker/بعيد/متين.
+- **تمنح محولات CLI** الوكيل وصولاً منظمًا إلى أدوات سطر الأوامر
+  (`gh`، `ffmpeg`، `stripe`) مع الاكتشاف والتحقق من التوفر و
+  شكل نتيجة متسق.
+
+يشترك كلاهما في قيد تشغيل واحد: يعتمدان على روابط نظام Node.js ويقومان بذلك
+لا يتم تشغيله على أوقات تشغيل الحافة/العامل - راجع [Edge and serverless](#edge-serverless).
+
+## ما هو مستند البرمجة الذي أريده؟ {#which-doc}
+
+| تريد...                                                                        | استخدام                                      |
+| ------------------------------------------------------------------------------ | -------------------------------------------- |
+| قم بتبديل الواجهة الخلفية التي تقوم بتشغيل **أداة `run-code`** للوكيل          | **محولات وضع الحماية** (هذه الصفحة)          |
+| قم بلف أداة CLI (`gh`، `ffmpeg`) ليتصل بها الوكيل                              | **محولات CLI** (هذه الصفحة)                  |
+| عرض نمط Claude/Codex **مساحة عمل الترميز UI**                                  | [Agent-Native Code UI](/docs/code-agents-ui) |
+| تشغيل Claude Code / Codex / Pi **كوكيل**، باستخدام الحلقة + الأدوات الخاصة بهم | [Harness Agents](/docs/harness-agents)       |
+
+# محولات وضع الحماية
+
+تقوم أداة `run-code` بتشغيل JavaScript الذي يوفره الوكيل في بيئة معزولة. **محولات Sandbox** تأخذ في الاعتبار مشكلة _التنفيذ_ من تلك الأداة بحيث يمكن تبديل الواجهة الخلفية - عملية فرعية محلية بشكل افتراضي، أو مشغل Docker / بعيد / دائم - دون لمس حلقة الوكيل، أو `run-code.ts`، أو جسر المضيف المحلي، أو env Scrub، أو تنسيق الإخراج.
+
+## لماذا التماس {#why}
+
+تنتج الواجهة الخلفية الافتراضية عملية فرعية محلية مؤمنة للعقدة. هذا مقيد بعملية الاستضافة: على النظام الأساسي المستضاف، فإنه يشارك سقف التنفيذ الناعم لحلقة الوكيل (حوالي 40 ثانية قبل انتهاء المهلة/الاستمرار). يعد المحول البعيد أو المتين بمثابة الرافعة لتجاوز هذا السقف - فهو يقوم بتشغيل مهام البيانات الكبيرة حتى اكتمالها بشكل مستقل عن دورة حياة الطلب.
+
+يعني إبقاء العقد محدودًا أن المحول البعيد يرث نفس الوضع الأمني. تحافظ العملية الأصلية على ملكية كل شيء يحمل سرًا: فهي تبني وحدة وضع الحماية، وتدير جسر المضيف المحلي (الذي يحتفظ بسياق الطلب ويطبق قوائم المضيف المسموح بها + حراس SSRF)، وينظف البيئة، وينسق المخرجات. يتلقى المحول فقط مصدر وحدة **غير سري** تم إعداده بالفعل بالإضافة إلى حدود الموارد — فهو مسؤول فقط عن تشغيله والتقاط حالة stdout/stderr/exit.
+
+```an-diagram title="The parent keeps the secrets; the adapter only runs code" summary="run-code builds the module and runs the loopback bridge; the adapter receives a non-secret module + limits and returns stdout/stderr/exit."
+{
+  "html": "<div class=\"diagram-sandbox\"><div class=\"diagram-box\" data-rough><strong>Parent process</strong><small class=\"diagram-muted\">builds module · loopback bridge · env scrub · output format</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">non-secret module + limits &rarr;</div><div class=\"diagram-pill ok\">&larr; stdout / stderr / exitCode</div><div class=\"diagram-pill\">&harr; bridge calls (127.0.0.1)</div></div><div class=\"diagram-panel center\" data-rough><strong>SandboxAdapter.run</strong><small class=\"diagram-muted\">local child · Docker · remote · durable</small></div></div>",
+  "css": ".diagram-sandbox{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sandbox .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-sandbox .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## الواجهة {#interface}
+
+يعيش خط التماس في قلب `packages/core/src/coding-tools/sandbox/` — `adapter.ts` (العقد)، `index.ts` (التحديد: `getSandboxAdapter()` / `registerSandboxAdapter()`)، و`local-child-process-adapter.ts` (الافتراضي). يتم توصيله داخل العبوة بواسطة `run-code.ts`؛ يقوم المضيف بتوصيل واجهة خلفية مختلفة من خلال مساعد التسجيل `index.ts` (أو، بالنسبة لواجهة Docker الخلفية، عبر [blueprint](/docs/blueprint-installer) الذي يحرر هذه الملفات مباشرة).
+
+```an-file-tree title="The sandbox seam in core"
+{
+  "title": "packages/core/src/coding-tools/sandbox/",
+  "entries": [
+    { "path": "adapter.ts", "note": "the SandboxAdapter contract (SandboxRunRequest / SandboxRunResult)" },
+    { "path": "index.ts", "note": "selection: getSandboxAdapter() / registerSandboxAdapter()" },
+    { "path": "local-child-process-adapter.ts", "note": "the default backend — locked-down Node child process" },
+    { "path": "../run-code.ts", "note": "wires the seam; never changes when you swap backends" }
+  ]
+}
+```
+
+تطبق كل واجهة خلفية `SandboxAdapter`:
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+الطلب والنتيجة صغيرة ومبهمة عن عمد:
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## الافتراضي: `LocalChildProcessAdapter` {#default}
+
+بشكل جاهز، تقوم `getSandboxAdapter()` بإرجاع `LocalChildProcessAdapter` (`id: "local-child-process"`). وهو يحافظ على سلوك `run-code` التاريخي بايت مقابل بايت:
+
+- تتم كتابة مصدر الوحدة المجهزة إلى مجلد مؤقت جديد.
+- يركض الطفل مع البيئة المنظفة (بدون أسرار)، مع الإشارة إلى `TMPDIR`/`TEMP`/`TMP` داخل صندوق الرمل.
+- عندما يكون نموذج إذن العقدة متاحًا (`--permission`، أو `--experimental-permission` على العقدة 20)، يُمنع الطفل من الوصول إلى نظام الملفات خارج الدليل المؤقت الخاص به، بالإضافة إلى العمليات الفرعية والعاملين والإضافات الأصلية. الشبكة الصادرة _ليست_ محظورة بواسطة نموذج الأذونات — ولكن فرك env يعني أن هذه الطلبات لا تحمل أي بيانات اعتماد، وجميع المكالمات التي تمت مصادقتها تمر عبر جسر الاسترجاع الخاص بالوالد.
+- ترسل المهلة `SIGTERM`، ثم `SIGKILL` بعد فترة سماح مدتها ثانيتان.
+- يتم تنظيف الملفات المؤقتة بأفضل جهد بعد التشغيل.
+
+> [!WARNING]
+> يستخدم المحول الافتراضي `node:child_process`، وهو غير موجود في أوقات تشغيل الحافة/العامل. قم بتشغيل `run-code` في بيئة Node.js القياسية، أو قم بتسجيل محول عن بعد — راجع [Edge and serverless](#edge-serverless).
+
+## تحديد محول {#selection}
+
+ترتيب الدقة - يفوز المحول المسجل بشكل صريح؛ وإلا فإن env var يحدد خيارًا مدمجًا؛ وإلا فسيتم استخدام الإعداد الافتراضي المحلي:
+
+```text
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### `AGENT_NATIVE_SANDBOX` env var {#env}
+
+يحدد المحول المضمن حسب المعرف. حاليًا يتم توصيل `local` (الافتراضي) فقط؛ تعود القيم غير المعروفة إلى المستوى المحلي بدلاً من فشل التشغيل.
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+تتجاوز العملية المضيفة الواجهة الخلفية لجميع استدعاءات `run-code` اللاحقة من خلال `index.ts` الخاص بالوصلة - على سبيل المثال، لتشغيل كل استدعاء في حاوية بعيدة:
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## التماس لعداء متين {#durable}
+
+هذه الواجهة هي بمثابة التماس لصندوق الحماية البعيد/المتين في المستقبل. سيقوم المحول البعيد أو المتين (Docker، أو مشغل نمط Vercel-Sandbox، أو عامل الخلفية في قائمة الانتظار):
+
+1. تنفيذ `SandboxAdapter.run` في وقت التشغيل خارج العملية.
+2. قم بتوصيل جسر الاسترجاع (أو مكالمات الجسر الوكيل إلى الأصل).
+3. السماح بتشغيل مهام البيانات الكبيرة حتى الاكتمال بشكل مستقل عن دورة حياة الطلب - بما يتجاوز الحد الأقصى المستضاف لبرنامج تنفيذ التعليمات البرمجية الذي يبلغ حوالي 40 ثانية والذي يحد محول العملية الفرعية المحلي.
+
+قم بتسجيله تحت قيمة `AGENT_NATIVE_SANDBOX` جديدة (على سبيل المثال، `remote`) و/أو عبر `registerSandboxAdapter()`. لا تتغير حلقة الوكيل و`run-code.ts` أبدًا.
+
+> [!TIP]
+> يُصدر مخطط `agent-native add sandbox docker` وصفة كاملة ومكتفية ذاتيًا لتنفيذ محول Docker مقابل هذا التماس. انظر [Blueprint Installer](/docs/blueprint-installer).
+
+# محولات CLI
+
+تغطي وصلة المحول الأخرى أداة سطر أوامر واحدة (`gh`، `ffmpeg`، `stripe`، `aws`) حتى يتمكن الوكيل من اكتشافها والتحقق من تثبيتها وتشغيلها باستخدام نتيجة كود stdout/stderr/exit متسقة. يقوم كل محول CLI بتنفيذ `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+بالنسبة لمعظم CLI، تقوم `ShellCliAdapter` بتغليف أي ثنائي بافتراضيات معقولة، وتقوم `CliRegistry` بجمع المحولات لاكتشاف وقت التشغيل:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({
+    command: "gh",
+    description: "GitHub CLI — manage repos, PRs, issues, and releases",
+  }),
+);
+
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+قم بلف مكالمة CLI في `defineAction` لعرضها على سطح الحركة. راجع المرجع السريع [CLI Adapters](/docs/cli-adapters) للتعرف على خيارات `ShellCliAdapter` والمحولات المخصصة ونمط التفاف الإجراء.
+
+## الحافة وبدون خادم {#edge-serverless}
+
+> [!WARNING]
+> تعتمد كل من طبقات المحول على روابط نظام Node.js. تستخدم محولات Sandbox `LocalChildProcessAdapter` وCLI (`ShellCliAdapter` والمحولات المخصصة) `node:child_process` (`execFile` / `spawn`)، والتي **غير موجودة** في أوقات تشغيل الحافة/العامل مثل Cloudflare Workers أو Netlify Edge Functions. إذا قمت بنشر مسارات الخادم إلى إعدادات الحافة المسبقة هذه، فإن تنفيذ هذه المحولات يؤدي إلى حدوث استثناء في وقت التشغيل. قم بتشغيل نقاط نهاية المحول ومهامه في بيئة Node.js القياسية (حاويات الخادم التقليدية أو وظائف Node بدون خادم) - أو، بالنسبة لوصلة وضع الحماية، سجل محولًا عن بعد يشحن العمل خارج العملية.
+
+## ما هي الخطوة التالية
+
+- [**CLI Adapters**](/docs/cli-adapters) — المرجع السريع لدرزة CLI
+- [**Blueprint Installer**](/docs/blueprint-installer) — يطبع `agent-native add sandbox docker` وصفة محول Docker
+- [**Agent Teams**](/docs/agent-teams) — تفويض العمل الثقيل إلى الوكلاء الفرعيين
+- [**Security**](/docs/security) — وضع القائمة المسموح بها لفرك البيئة والجسر