@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,349 @@
+---
+title: "وكلاء تسخير"
+description: "قم بتشغيل Claude Code، وCodex، وPi، وغيرها من أدوات الترميز الكاملة كوكلاء مضمنين داخل Agent-Native، مع الحلقة الخاصة بهم، ووضع الحماية، والأدوات الأصلية، وجلسات SQL المدعومة القابلة للاستئناف."
+search: "وكلاء تسخير AgentHarness ai-sdk رمز HarnessAgent Claude Codex Pi Cursor Mastra وكيل الترميز المضمن ResolveAgentHarness startAgentHarnessRun أدوات مضيف وضع الحماية للجلسة القابلة للاستئناف"
+---
+
+# وكلاء تسخير
+
+> **من هو هذا:** المؤلفون المضيفون يقومون بتوصيل وقت تشغيل كامل للترميز (رمز Claude،
+> Codex, Pi) إلى Agent-Native كوكيل. بناء التطبيق؟ ابدأ بـ
+> [Creating Templates](/docs/creating-templates).
+
+وكيل التسخير هو وقت تشغيل كامل للوكيل — رمز Claude، وCodex، وPi، وما شابه ذلك —
+يمتلك حلقة خاصة به، ومساحة عمل، وأدوات ملفات أصلية، وحالة الجلسة، والضغط،
+نموذج الموافقة وسلوك وضع الحماية. يقوم Agent-Native بتشغيل هذه من خلال
+**`AgentHarness`** الركيزة في `@agent-native/core/agent/harness`، تتدفق
+تدرج الأحداث في النص العادي، وتستمر في جلستها الأصلية بحيث تكون سلسلة رسائل
+يمكن إيقافه مؤقتًا واستئنافه.
+
+يختلف هذا عن وكيل الدردشة المدمج وعن إحضار الدردشة الخاصة بك
+وقت التشغيل. الوكيل المدمج و`AgentEngine` مخصصان لنموذج واحد ذهابًا وإيابًا
+أسفل `runAgentLoop`. الحزام ليس مزود `AgentEngine` - فهو يقوم بتشغيل
+حلقة خاصة بها من البداية إلى النهاية، لذا فإن Agent-Native يقودها كجلسة، وليس كجلسة واحدة
+استدعاء النموذج.
+
+```an-diagram title="A harness owns its loop; Agent-Native drives the session" summary="The AgentHarness substrate creates/resumes the native session, streams its events into the normal transcript, and persists resumeState in SQL between turns."
+{
+  "html": "<div class=\"diagram-harness\"><div class=\"diagram-box\" data-rough><strong>AgentHarness substrate</strong><small class=\"diagram-muted\">@agent-native/core/agent/harness</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><strong>Native harness loop</strong><small class=\"diagram-muted\">Claude Code · Codex · Pi — own tools, sandbox, compaction</small></div><div class=\"diagram-col\"><div class=\"diagram-pill accent\">events &rarr; transcript</div><div class=\"diagram-pill ok\">resumeState &rarr; SQL session</div></div></div>",
+  "css": ".diagram-harness{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-harness .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-harness .diagram-arrow{font-size:22px;line-height:1}.diagram-harness .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## ما هو مستند البرمجة الذي أريده؟ {#which-doc}
+
+| تريد...                                                                        | استخدام                                      |
+| ------------------------------------------------------------------------------ | -------------------------------------------- |
+| تشغيل Claude Code / Codex / Pi **كوكيل**، باستخدام الحلقة + الأدوات الخاصة بهم | **وكلاء الاستفادة** (هذه الصفحة)             |
+| عرض نمط Claude/Codex **مساحة عمل الترميز UI**                                  | [Agent-Native Code UI](/docs/code-agents-ui) |
+| قم بتبديل الواجهة الخلفية التي تقوم بتشغيل **أداة `run-code`**                 | [Adapters](/docs/sandbox-adapters)           |
+| قم بلف أداة CLI (`gh`، `ffmpeg`) ليتصل بها الوكيل                              | [Adapters](/docs/sandbox-adapters)           |
+
+الأسطح المجاورة: ضع الوكيل الذي أنشأته في مكان آخر خلف دردشة Agent-Native
+UI مع [`AgentChatRuntime`](/docs/native-chat-ui#byo-agent-runtimes)؛ دع
+مكالمة مضيف MCP خارجية إلى تطبيقك عبر [External Agents](/docs/external-agents)؛
+يتم تشغيل الخلفية/الوكيل الفرعي باستخدام [Custom Agents & Teams](/docs/agent-teams).
+
+## أدوات مساعدة مدمجة {#built-in}
+
+يسجل `registerBuiltinAgentHarnesses()` ثلاثة محولات مدعومة بـ AI SDK
+`HarnessAgent`:
+
+| الاسم                        | وقت التشغيل | وضع الحماية | الموافقات |
+| ---------------------------- | ----------- | ----------- | --------- |
+| `ai-sdk-harness:claude-code` | رمز Claude  | نعم         | نعم       |
+| `ai-sdk-harness:codex`       | Codex       | نعم         | لا        |
+| `ai-sdk-harness:pi`          | باي         | لا          | نعم       |
+
+حزم وقت التشغيل الخاصة بها هي **تبعيات نظير اختيارية** ويتم تحميلها ببطء، لذا
+التطبيق الذي لا يستخدم أداة التثبيت مطلقًا لا يدفع ثمنه. يحمل كل محول
+تلميح `installPackage` (على سبيل المثال `@ai-sdk/harness@canary
+@ai-sdk/harness-codex@canary`); `resolveAgentHarness` يُجري تثبيتًا واضحًا
+خطأ إذا كانت الحزم مفقودة، و`isAgentHarnessPackageInstalled(entry)`
+يتيح لك التحقق أولاً.
+
+يسجل `registerBuiltinAgentHarnesses()` أيضًا أحزمة [ACP](#acp)
+(`acp`, `acp:gemini`, `acp:claude-code`).
+
+## وكلاء ACP {#acp}
+
+يمكن أن يعمل Agent-Native كعميل [ACP](https://agentclientprotocol.com) (العميل
+البروتوكول) **العميل** وقيادة وكيل الترميز المحلي — Gemini CLI، Claude Code،
+أو أي وكيل متوافق مع ACP — من خلال نفس الركيزة. يعمل الوكيل باعتباره
+عملية فرعية محلية تتحدث JSON-RPC مفصولة بسطر جديد عبر stdio؛ محرر ACP
+↔ نموذج الوكيل هو هذا الشكل بالضبط.
+
+تم تحديد نطاق هذا المحول لـ **الترميز المحلي**. ترث العملية الفرعية
+البيئة الأصلية، لذلك يقوم الوكيل بإعادة استخدام أي معلومات تسجيل دخول CLI محلية لديه بالفعل
+(على سبيل المثال، مصادقة `gemini` أو `claude` في الدليل الرئيسي للمستخدم). إنها ليست
+نقل مستضاف أو في وضع الحماية، وهو ليس وسيلة نقل للدردشة/A2A - بالنسبة لهؤلاء،
+راجع [Agent Surfaces](/docs/agent-surfaces).
+
+| الاسم             | الأمر الافتراضي                                | قابل للاستئناف\* |
+| ----------------- | ---------------------------------------------- | ---------------- |
+| `acp`             | _(توريد `command`/`args` عبر التكوين)_         | نعم              |
+| `acp:gemini`      | `npx -y @google/gemini-cli --experimental-acp` | نعم              |
+| `acp:claude-code` | `npx -y @zed-industries/claude-code-acp`       | نعم              |
+
+\*تعمل السيرة الذاتية عندما يعلن الوكيل عن قدرة `loadSession` و
+سيتدهور إلى جلسة جديدة.
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+
+// A built-in preset (command/args are overridable through the resolve config):
+const adapter = resolveAgentHarness("acp:gemini");
+
+// Or any ACP agent by command:
+const custom = resolveAgentHarness("acp", {
+  command: "gemini",
+  args: ["--experimental-acp"],
+});
+```
+
+يعد نقل البروتوكول (`@zed-industries/agent-client-protocol`) اختياريًا
+يتم تحميل التبعيات ببطء من خلال تلميح `installPackage`، تمامًا مثل AI SDK
+يسخر. الوكيل الثنائي نفسه (`@google/gemini-cli`،
+`@zed-industries/claude-code-acp`,...) هو CLI خارجي منفصل؛ الإعدادات المسبقة
+قم بتشغيله من خلال `npx` وسيظل الأمر/الوسائط قابلة للتجاوز لأن الوكيل ACP
+لا تزال إشارات الإدخال تتطور.
+
+يتم تعيين `permissionMode` إلى ACP `session/request_permission` باستخدام استدعاء الأداة
+اكتب تقارير الوكيل: يتم تشغيل القراءات دائمًا، ويتم تشغيل التعديلات ضمن `allow-edits`، و
+كل شيء محفوف بالمخاطر يطالب إلا `allow-all`. تظهر الموافقات كالمعتاد
+أحداث `approval-request`. يخدم المحول `fs/read_text_file` و
+`fs/write_text_file` مقابل مساحة عمل الجلسة (رفض المسارات التي تهرب
+it) ويكتب أحداث `file-change`؛ لا يتم الإعلان عن الطرق الطرفية،
+لذلك يستخدم الوكيل غلافه الخاص.
+
+## مصادقة Codex: الكود UI مقابل أدوات الحماية {#codex-auth}
+
+يوجد سطحان Codex، ويتم المصادقة عليهما بشكل مختلف:
+
+- **Agent-Native Code / Desktop** يقوم بتشغيل `codex exec` على جهاز المستخدم. إذا
+  قام المستخدم بتشغيل `codex login`، وهذا التشغيل المحلي يعيد استخدام ChatGPT
+  الاشتراك أو مفتاح API يصادق على تقارير Codex CLI المثبتة من خلال
+  `codex login status`.
+- **`ai-sdk-harness:codex`** يقوم بتحميل `@ai-sdk/harness-codex`، الذي يقوم بتشغيل Codex
+  داخل صندوق الحماية الخاص بالحزام من خلال `@openai/codex-sdk`. لا يحدث ذلك بصمت
+  ارث تسجيل دخول `~/.codex` لسطح المكتب الخاص بالمستخدم لأن وضع الحماية قد يكون بعيدًا
+  أو معزولة. بالنسبة إلى صناديق الحماية الموثوقة/الخاصة، يمكنك الاشتراك باستخدام `codexCliAuth: true`;
+  ينسخ Agent-Native ملف المصادقة Codex CLI المحلي إلى وضع الحماية قبل
+  يبدأ الحزام. بالنسبة لصناديق الحماية المستضافة أو المشتركة، قم بتكوين مفتاح/بوابة API
+  المصادقة بدلاً من ذلك.
+
+لذلك إذا سأل شخص ما عن الحزمة التي تحمل مسار Codex OAuth: للتشفير المحلي
+الجلسات، استخدم `@agent-native/core` / Desktop بالإضافة إلى المثبت
+`@openai/codex` CLI و`codex login`. بالنسبة إلى وضع الحماية `ai-sdk-harness:codex`،
+استخدم الاشتراك الصريح `codexCliAuth` عند نسخ تسجيل الدخول هذا إلى وضع الحماية
+مقبول.
+
+```ts
+const adapter = resolveAgentHarness("ai-sdk-harness:codex", {
+  codexCliAuth: true,
+});
+```
+
+`codexCliAuth: true` يقرأ `CODEX_HOME/auth.json` أو `~/.codex/auth.json`. إلى
+أشر إلى تسجيل دخول محلي مختلف، وقم بالتمرير
+`{ codexCliAuth: { codexHome: "/path/to/.codex" } }` أو
+`{ codexCliAuth: { authJsonPath: "/path/to/auth.json" } }`.
+
+## التسجيل والحل {#register-resolve}
+
+```ts
+import {
+  registerBuiltinAgentHarnesses,
+  resolveAgentHarness,
+} from "@agent-native/core/agent/harness";
+
+registerBuiltinAgentHarnesses();
+const adapter = resolveAgentHarness("ai-sdk-harness:codex");
+```
+
+ترجع `resolveAgentHarness(name, config?)` `AgentHarnessAdapter`. ال
+تتم إعادة توجيه `config` الاختياري إلى مصنع المحولات — لمحولات AI SDK
+الذي يتم تعيينه إلى `AiSdkHarnessAdapterOptions` (`label`، `description`،
+`permissionMode`، و`harnessOptions`، و`agentOptions`، وCodex فقط
+`codexCliAuth`). استخدم `listAgentHarnesses()` لتعداد ما تم تسجيله من أجله
+منتقي.
+
+## أجري دورة {#run-a-turn}
+
+`startAgentHarnessRun` بتوصيل جلسة تسخير إلى مدير التشغيل المشترك
+دورة الحياة. فهو ينشئ (أو يعيد استخدام) الجلسة الأصلية، ويستمر فيها، ويبث
+يحول كل حدث تسخير ويترجمه إلى أحداث نصية ويفصل
+حالة قابلة للاستئناف عند اكتمال الدور.
+
+```ts
+import { startAgentHarnessRun } from "@agent-native/core/agent/harness";
+
+const run = startAgentHarnessRun({
+  runId,
+  threadId,
+  adapter,
+  input: { prompt },
+  createSession: {
+    sessionId,
+    resumeState, // opaque value from a previous turn, if resuming
+    instructions,
+    sandbox, // required for sandboxed harnesses — see Sandbox Adapters
+    permissionMode: "allow-reads",
+    tools, // a narrow, intentional set of host tools (see below)
+  },
+  ownerEmail,
+  orgId,
+});
+```
+
+يرجع `startAgentHarnessRun` `ActiveRun` من مدير التشغيل، وبالتالي فإن الدور
+يظهر من خلال مسارات التشغيل الحالية والنص والإلغاء تمامًا مثل
+تشغيل أي وكيل آخر. قم بتمرير `session` الذي تم إنشاؤه بالفعل بدلاً من `createSession`
+لمتابعة الجلسة التي تحتفظ بها في الذاكرة.
+
+## الجلسات والاستئناف {#sessions}
+
+يمتلك الحزام حالة جلسة أصلية طويلة الأمد. يستمر Agent-Native في SQL
+حتى يتمكن الخيط من البقاء عبر المنعطفات والعمليات والنشر. `resumeState`
+**غير شفاف** — يقوم Agent-Native بتخزينه وإعادته، ولكن لا يتم فحصه أو فحصه مطلقًا
+يفسرها.
+
+```an-diagram title="Resume across turns, processes, and deploys" summary="Each turn detaches an opaque resumeState into SQL; the next turn feeds it back into createSession instead of replaying chat history."
+{
+  "html": "<div class=\"diagram-resume\"><div class=\"diagram-node\" data-rough>Turn N<br><small class=\"diagram-muted\">streamTurn</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>detach &rarr; resumeState<br><small class=\"diagram-muted\">opaque · SQL harness session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>Turn N+1<br><small class=\"diagram-muted\">createSession.resumeState</small></div></div>",
+  "css": ".diagram-resume{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-resume .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```ts
+import {
+  getLatestAgentHarnessSessionForThread,
+  listAgentHarnessSessions,
+} from "@agent-native/core/agent/harness";
+
+const last = await getLatestAgentHarnessSessionForThread(threadId);
+// Feed last?.resumeState into createSession.resumeState on the next turn.
+```
+
+يكشف المتجر أيضًا عن `saveAgentHarnessSession`، `updateAgentHarnessSession`،
+`getAgentHarnessSession`, `getAgentHarnessSessionByRunId`,
+`markAgentHarnessSessionStopped`، و`ensureAgentHarnessSessionTables`.
+`startAgentHarnessRun` يستدعي مسارات الحفظ/التحديث/الإيقاف نيابةً عنك؛ الوصول إليهم
+مباشرة فقط في مضيف مخصص.
+
+## أدوات وأذونات المضيف {#host-tools}
+
+يجلب الحزام أدواته الأصلية (القراءة، والتحرير، والكتابة، والصدفة، وما إلى ذلك)، وهكذا
+لا يمكنك **إعادة عرض تحرير الملفات كأدوات مضيفة. قم بتمرير **ضيق فقط،
+المجموعة المقصودة\*\* من Agent-Native actions حتى `createSession.tools` عندما
+تريد أن يصل الحزام إلى عمليات تطبيق معينة - واحتفظ بـ `defineAction`
+المصادقة وسياق الطلب والمهلات والاقتطاع وبيانات التعريف للقراءة فقط سليمة عندما
+أنت تفعل ذلك.
+
+يحدد `permissionMode` ما قد يفعله الحزام دون موافقة:
+
+| الوضع         | المعنى                                                               |
+| ------------- | -------------------------------------------------------------------- |
+| `allow-reads` | افتراضي. تشغيل القراءات؛ التعديلات ومطالبة actions المحفوفة بالمخاطر |
+| `allow-edits` | تشغيل عمليات القراءة والتحرير؛ موجه actions الخطير الآخر             |
+| `allow-all`   | لا توجد بوابة موافقة                                                 |
+
+عندما يتوقف الحزام مؤقتًا للموافقة عليه، فإنه يصدر حدث `approval-request` و
+تم وضع علامة `idle` على الجلسة مع تسجيل الموافقة المعلقة، لذا يمكن لـ UI
+أبرزها واستأنفها بناءً على قرار المستخدم. انظر
+[Human Approval](/docs/human-approval) لسطح الموافقة.
+
+## الأحداث {#events}
+
+تقوم جلسة تسخير ببث قيم `AgentHarnessEvent`، والتي Agent-Native
+يترجم إلى دفق `AgentChatEvent` القياسي باستخدام
+`agentHarnessEventToAgentChatEvents`. The event union covers `text-delta`,
+`thinking-delta`، `activity`، `tool-start`، `tool-done` (والتي يمكنها حمل
+حمولة `mcpApp` للأدوات الأصلية)، `approval-request`، `file-change`،
+`compaction`، و`usage`، و`error`، و`done`. لأن نتائج الأداة تتدفق عبر
+نفس الترجمة، ولا تزال الأدوات الأصلية التي تم الإعلان عنها عن إجراء تعرض - راجع
+[Native Chat UI](/docs/native-chat-ui).
+
+## يعمل في الخلفية وUI {#background-runs}
+
+يقوم Harness بتشغيل المشروع في شكل `BackgroundAgentRun` المشترك مع
+`createAgentHarnessBackgroundAgentController()` ومتاح من خلال
+مسارات التشغيل الموجودة كـ `goalId=agent-harness`. وهذا يعني Claude طويل الأمد
+تظهر جلسة التعليمات البرمجية أو Codex في نفس أسطح التشغيل في الخلفية والنص
+مثل فرق الوكلاء والمحولات الأخرى، باستخدام `listAgentHarnessBackgroundRuns`،
+`listAgentHarnessBackgroundTranscriptEvents`، `getAgentHarnessBackgroundRun`، و
+`stopAgentHarnessBackgroundRun` متاح للمضيفين المخصصين.
+
+## المحولات المخصصة {#custom-adapters}
+
+لتغليف وقت تشغيل ليس أحد العناصر المضمنة، قم بتنفيذ
+`AgentHarnessAdapter` وقم بتسجيله. يعلن المحول عن إمكانياته و
+ينشئ جلسات؛ تعرض الجلسة `streamTurn` و`continueTurn` الاختيارية،
+`approve`، و`detach`، و`stop`، و`destroy`.
+
+```ts
+import {
+  registerAgentHarness,
+  type AgentHarnessAdapter,
+} from "@agent-native/core/agent/harness";
+
+const myHarness: AgentHarnessAdapter = {
+  name: "acme:my-coder",
+  label: "Acme Coder",
+  description: "Runs the Acme coding agent.",
+  installPackage: "@acme/coder",
+  capabilities: {
+    sandbox: true,
+    resumable: true,
+    approvals: true,
+    hostTools: true,
+    fileEvents: true,
+  },
+  async createSession(opts) {
+    // Build your native session and adapt it to AgentHarnessSession.
+    return createAcmeSession(opts);
+  },
+};
+
+registerAgentHarness({
+  name: myHarness.name,
+  label: myHarness.label,
+  description: myHarness.description,
+  installPackage: myHarness.installPackage,
+  capabilities: myHarness.capabilities,
+  create: () => myHarness,
+});
+```
+
+احتفظ بحزمة وقت التشغيل اختيارية من خلال الاستيراد الديناميكي في `createSession` و
+تلميح `installPackage`. بالنسبة إلى أدوات الترميز المدعومة بالجسر، يلزم وجود
+موفر وضع الحماية/مساحة العمل بدلاً من تشغيل وكيل ترميز عشوائي في
+عملية المضيف — راجع [Sandbox Adapters](/docs/sandbox-adapters). محول AI SDK
+(`createAiSdkHarnessAdapter`، مدعوم بـ `HarnessAgent` من `@ai-sdk/harness`) هو
+تنفيذ واحد لهذا العقد، وليس التجريد العام.
+
+## لا تفعل ذلك {#donts}
+
+- لا تقم بإضافة رمز Claude أو Codex أو Cursor أو Mastra أو Pi كـ `AgentEngine`. هم
+  تملك الحلقة الخاصة بهم؛ يؤدي تشغيل واحدة تحت `AgentEngine.stream()` إلى تشغيل الحلقة بشكل مزدوج
+  ويفقد دلالات دورة حياة الجلسة.
+- لا تقم بإعادة تشغيل سجل الدردشة Agent-Native الكامل في كل دورة. استئناف
+  جلسة الحزام باستخدام `resumeState` بدلاً من ذلك.
+- لا تقم بتخزين `resumeState` في `application_state`. إنه ينتمي إلى الحزام
+  جدول SQL للجلسة.
+- لا تعرض كل إجراء من إجراءات التطبيق لكل جلسة استخدام بشكل افتراضي. سلمها
+  مجموعة أدوات صغيرة ومتعمدة.
+
+## المستندات ذات الصلة {#related-docs}
+
+- [Native Chat UI](/docs/native-chat-ui) — ضع وكيلك الخاص خلف الدردشة UI مع `AgentChatRuntime`.
+- [Agent Surfaces](/docs/agent-surfaces) - اختر التطبيق بلا رأس، أو الدردشة، أو السيارة الجانبية، أو التطبيق الكامل.
+- [Agent-Native Code UI](/docs/code-agents-ui) — سطح مساحة عمل البرمجة القابلة لإعادة الاستخدام.
+- [Custom Agents & Teams](/docs/agent-teams) — عمليات التشغيل في الخلفية وتفويض الوكيل الفرعي.
+- [Sandbox Adapters](/docs/sandbox-adapters) — واجهات خلفية قابلة للتنفيذ لأدوات البرمجة.
+- [Human Approval](/docs/human-approval) — يتم استخدام مجموعة أحزمة السطح المعتمدة.

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

@@ -0,0 +1,86 @@
+---
+title: "موافقات الإنسان في الحلقة"
+description: "إيقاف الوكيل مؤقتًا قبل تشغيل الإجراء عالي العواقب — تُصدر بوابة needApproval الخاصة بـ defineAction حدث موافقة_مطلوب، ويوافق الإنسان، وعندها فقط يتم تنفيذ الأداة."
+---
+
+# موافقات الإنسان داخل الحلقة
+
+يجب تشغيل معظم actions. القليل منها - إرسال بريد إلكتروني، وشحن البطاقة، وحذف الحساب - هي أمور خارجية ويصعب التراجع عنها، ولا تريد أن يقوم الوكيل بذلك بشكل مستقل. بالنسبة إلى هؤلاء، `defineAction` لديه **بوابة موافقة** للاشتراك: عندما يحاول الوكيل استدعاء الإجراء، تتوقف الحلقة مؤقتًا، وتظهر إمكانية الموافقة/الرفض للإنسان، وتشغيل الإجراء _فقط_ بعد موافقة الإنسان على هذا الاتصال المحدد.
+
+> [!WARNING]
+> حافظ على الموافقات نادرة. كل إجراء مسور يمثل نقطة توقف صعبة في حلقة العميل - فهو يقطع التشغيل ويتطلب رحلة ذهابًا وإيابًا من الإنسان. استخدم `needsApproval` فقط للعمليات ذات العواقب العالية، والتي يصعب التراجع عنها، والتي تواجه الخارج. إذا وجدت نفسك تتابع القراءة أو الكتابة الروتينية، فأنت مخطئ. الإعداد الافتراضي هو **إيقاف**، ويجب أن يتم إيقافه في كل إجراء تقريبًا.
+
+## بوابة `needsApproval` {#needs-approval}
+
+قم بتعيين `needsApproval` على `defineAction`. يقبل قيمة منطقية أو مسندًا:
+
+```an-annotated-code title="Gating the one consequential action"
+{
+  "filename": "actions/send-email.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Send an email via Gmail.\",\n  schema: z.object({\n    to: z.string(),\n    subject: z.string(),\n    body: z.string(),\n  }),\n  // Sending is outward-facing and hard to undo, so the agent can never send\n  // without a human approving the specific call. Drafting/queueing is\n  // unaffected — only the real send is gated.\n  needsApproval: true,\n  run: async (args) => {\n    /* ...actually send... */\n  },\n});",
+  "annotations": [
+    { "lines": "10", "label": "The whole gate", "note": "One flag. With it truthy and the call unapproved, the loop stops before `run` — the model never reaches the side effect on its own." },
+    { "lines": "11-13", "label": "run() is untouched", "note": "The handler stays the same. Approval is enforced by the loop around it, not by anything inside `run`." }
+  ]
+}
+```
+
+- **`needsApproval: true`** — تتطلب الموافقة دائمًا.
+- **`needsApproval: (args, ctx) => boolean | Promise<boolean>`** — لا تتطلب الموافقة إلا عندما يكون المسند صحيحًا. بوابة مشروطة، على سبيل المثال. فقط للمستلمين الخارجيين أو فقط فوق حد الدولار:
+
+  ```النهاية
+  يحتاج إلى موافقة: (args) => !args.to.endsWith("@your-company.com"),
+  ```
+
+  احتفظ بالمسند نقيًا وسريعًا. **فشل في الإغلاق**: إذا تم طرح المسند، فإن إطار العمل يعامل ذلك على أنه "موافقة مطلوبة" بدلاً من تشغيل إجراء عالي العواقب بصمت.
+
+عند حذف `needsApproval`، يظل السلوك بايت مقابل بايت دون تغيير — لا توجد تكلفة إضافية على المسار المشترك.
+
+يعمل هذا بنفس الطريقة مع actions بنمط `parameters` القديم وactions المستند إلى المخطط، وللوكيل داخل التطبيق، والوكلاء الفرعيين، والمتصلين A2A، وMCP (يمر كل سطح وكيل عبر نفس الحلقة).
+
+## كيفية توقف الحلقة مؤقتًا {#loop}
+
+عندما يستدعي الوكيل إجراءً مسورًا ولم تتم الموافقة على هذا الاستدعاء المحدد بالفعل، فإن الحلقة **لا** تنفذ `run()`. بدلا من ذلك:
+
+1. يحل البوابة. بالنسبة للمسند، فإنه يستدعي `needsApproval(input, ctx)`؛ يتم التعامل مع الرمية على أنها "يجب الموافقة عليها" (تم إغلاق الفشل).
+2. يُصدر حدث `tool_start` (بحيث يُظهر UI المكالمة) متبوعًا مباشرة بحدث **`approval_required`**، ثم يوقف الدور. لا يحدث التأثير الجانبي للإجراء أبدًا.
+
+يحمل حدث `approval_required` كل ما يحتاجه العميل لتوفير التكلفة:
+
+| الحقل         | اكتب     | ملاحظات                                                                             |
+| ------------- | -------- | ----------------------------------------------------------------------------------- |
+| `tool`        | `string` | اسم الإجراء الذي حاول الوكيل الاتصال به.                                            |
+| `input`       | كائن     | الوسيطات التي مررها الوكيل.                                                         |
+| `approvalKey` | `string` | **المفتاح الثابت** يقوم العميل بالتردد مرة أخرى للموافقة على _هذه المكالمة بالضبط_. |
+| `toolCallId`  | `string` | معرف استدعاء الأداة من جانب النموذج، عندما يكون متاحًا.                             |
+
+يتم اشتقاق `approvalKey` بشكل حتمي من اسم الأداة بالإضافة إلى مدخلاتها، لذا فإن نفس الاستدعاء المنطقي ينتج دائمًا نفس المفتاح. النموذج لا يراه أو يحدده أبدًا - فهو مجرد مصافحة بين إطار العمل وقدرة الموافقة البشرية.
+
+ترجع أداة الإيقاف المؤقت نتيجة تخبر النموذج بتوقف الدور مؤقتًا وعدم إعادة المحاولة، وبالتالي لا يدور النموذج.
+
+## كيف يوافق الإنسان {#approve}
+
+في `approval_required`، تعرض الدردشة UI قبول / رفض \*\* في استدعاء الأداة المتوقف مؤقتًا. يتم ربط هذا تلقائيًا في `AssistantChat` — ولا يمكنك إنشاءه لكل قالب.
+
+- **الموافقة** تعيد إصدار الدور (رسالة متابعة عادية) التي تحمل مفتاح المكالمة في `approvedToolCalls: [approvalKey]`. في المنعطف المُعاد إصداره، ترى البوابة المفتاح في المجموعة المعتمدة وتسمح بإجراء المكالمة المحددة بشكل طبيعي.
+- **الرفض** يرفض القدرة على التحمل محليًا؛ لا يتم إعادة إصدار أي شيء، لذلك لا يتم تشغيل الإجراء أبدًا.
+
+`approvedToolCalls` هو حقل في طلب الدردشة (`AgentChatRequest.approvedToolCalls`). تظل المفاتيح غير الموجودة فيه متوقفة مؤقتًا - فالموافقة على مكالمة واحدة لا توافق مطلقًا على المكالمات الأخرى بشكل صريح. نظرًا لأن المفتاح موجه للمحتوى، فإن الموافقة تسمح _بالاستدعاء بهذه الوسائط_؛ إذا اقترح النموذج لاحقًا إرسالًا مختلفًا، فهذا مفتاح جديد وموافقة جديدة.
+
+## من النهاية إلى النهاية {#flow}
+
+```an-diagram title="The approval interrupt" summary="A gated call pauses the turn before run() fires. Approval re-issues the turn carrying the call's key; only then does the side effect happen."
+{
+  "html": "<div class=\"diagram-approve\"><div class=\"diagram-box\" data-rough>Agent calls send-email</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel warn\" data-rough><strong>Gate truthy, call not yet approved</strong><small class=\"diagram-muted\">loop emits tool_start + approval_required { tool, input, approvalKey }</small><span class=\"diagram-pill warn\">turn pauses &mdash; run() did NOT execute</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Human clicks Approve in chat<br><small class=\"diagram-muted\">client re-issues the turn with approvedToolCalls: [approvalKey]</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-panel ok\" data-rough><span class=\"diagram-pill ok\">Gate sees the key &rarr; run() executes &rarr; email sends</span></div></div>",
+  "css": ".diagram-approve{display:flex;flex-direction:column;align-items:center;gap:8px}.diagram-approve .diagram-panel{display:flex;flex-direction:column;gap:6px;align-items:center;padding:12px 16px;text-align:center}.diagram-approve .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+الاستخدام الأساسي (والنادر عمدًا) لهذه البوابة في إطار العمل هو إجراء `send-email` لقالب البريد، والذي يقوم بتعيين `needsApproval: true` بحيث يتمكن الوكيل من الصياغة والانتظار بحرية ولكن لا يمكنه أبدًا إرسال رسالة دون موافقة الإنسان على الإرسال المحدد.
+
+## ذات صلة
+
+- [**Actions**](/docs/actions#needs-approval) — سطح `defineAction` الكامل، بما في ذلك `outputSchema` للتحقق من صحة القيم المرجعة.
+- [**Security**](/docs/security) — متى يتم الوصول إلى بوابة الموافقة مقابل إخفاء إجراء من النموذج.
+- [**Mail template**](/docs/template-mail) — `send-email` هو المثال المرجعي.

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

@@ -1,15 +1,18 @@
 ---
 title: "التدويل"
-description: "قم بتعريب تطبيقات Agent Native باستخدام كتالوجات locale مشتركة، واختيار اللغة، والرجوع إلى لغة المتصفح، ومحتوى docs حسب locale."
+description: "قم بترجمة تطبيقات Agent Native باستخدام كتالوجات محلية مشتركة، ومنتقي اللغة، ولغة احتياطية للمتصفح، ومحتوى المستندات المدرك للغة المحلية."
 ---
 
 # التدويل
 
-يمكن لتطبيقات Agent Native تعريب واجهة framework و templates عبر runtime المشترك `@agent-native/core/client/i18n`. يخزن framework اختيار لغة المستخدم في SQL settings، ويعرضه كـ actions، ويرجع إلى English عندما لا تكون string مترجمة في التطبيق بعد.
+يمكن لتطبيقات Agent Native توطين إطار العمل والنموذج UI من خلال
+وقت تشغيل `@agent-native/core/client/i18n`. يقوم الإطار بتخزين
+اختيار اللغة في إعدادات SQL، يعرضها كـ actions، ويعود إلى
+الإنجليزية عندما لا يترجم التطبيق سلسلة بعد.
 
-## Runtime {#runtime}
+## وقت التشغيل
 
-استخدم provider عبر `AppProviders`:
+استخدم الموفر من خلال `AppProviders`:
 
 ```tsx
 import { AppProviders, getLocaleInitScript } from "@agent-native/core/client";
@@ -27,11 +30,14 @@ const LOCALE_INIT_SCRIPT = getLocaleInitScript();
 </AppProviders>;
 ```
 
-يضبط `getLocaleInitScript()` قيم `lang` و `dir` و `window.__AGENT_NATIVE_LOCALE__` قبل React hydration. يمكن لمسارات SSR العامة استدعاء `resolveLocaleFromRequest()` من `@agent-native/core/server` وتمرير locale/catalog الناتج إلى script لتجنب hydration mismatches.
+يقوم `getLocaleInitScript()` بتعيين `lang` الأولي و`dir` و
+`window.__AGENT_NATIVE_LOCALE__` قبل هيدرات React. يمكن أن تكون مسارات SSR العامة
+اتصل بـ `resolveLocaleFromRequest()` من `@agent-native/core/server` وقم بتمرير
+تم حل الإعدادات المحلية/الكتالوج في هذا البرنامج النصي لتجنب عدم تطابق الماء.
 
-## Catalogs {#catalogs}
+## الكتالوجات
 
-كل template مترجم يحتفظ بالكتالوجات تحت `app/i18n/`:
+يحتفظ كل قالب مترجم بالكتالوجات ضمن `app/i18n/`:
 
 ```ts
 // app/i18n/index.ts
@@ -52,51 +58,88 @@ export const i18nCatalog = {
 } satisfies AgentNativeI18nCatalog;
 ```
 
-احزم `en-US` دائماً. استخدم dynamic import للكتالوجات غير English حتى ينزل المستخدمون locale النشط فقط. locale codes المدعومة هي `en-US` و `zh-CN` و `es-ES` و `fr-FR` و `de-DE` و `ja-JP` و `ko-KR` و `pt-BR` و `hi-IN` و `ar-SA`.
+حزمة `en-US` دائمًا. يتم استيراد الكتالوجات غير الإنجليزية بشكل ديناميكي للمستخدمين فقط
+قم بتنزيل اللغة النشطة. الرموز المحلية المدعومة هي `en-US`، `zh-CN`،
+`es-ES`، و`fr-FR`، و`de-DE`، و`ja-JP`، و`ko-KR`، و`pt-BR`، و`hi-IN`، و`ar-SA`.
 
-## UI {#ui}
+## UI
 
-استخدم `useT()` لنصوص الواجهة و `<LanguagePicker />` في settings:
+استخدم `useT()` لسلاسل الواجهة ثم ضع `<LanguagePicker />` على التطبيق
+صفحة `/settings`. يجب أن تعرض تطبيقات الشريط الجانبي **الإعدادات** في الشريط الجانبي للتطبيق؛
+رمز لغة الرأس هو مجرد اختصار.
 
 ```tsx
-import { LanguagePicker, useT } from "@agent-native/core/client";
+import {
+  LanguagePicker,
+  openAgentSettings,
+  useT,
+} from "@agent-native/core/client";
 
-function SettingsLanguageCard() {
+function SettingsPage() {
   const t = useT();
   return (
     <>
       <h2>{t("settings.languageTitle")}</h2>
       <LanguagePicker label={t("settings.languageLabel")} />
+
+      <h2>{t("settings.agentTitle")}</h2>
+      <p>{t("settings.agentDescription")}</p>
+      <button type="button" onClick={() => openAgentSettings()}>
+        {t("settings.openAgentSettings")}
+      </button>
     </>
   );
 }
 ```
 
-استخدم `useFormatters()` للتواريخ، والأرقام، والوقت النسبي، والقوائم. لا تضع تنسيق التاريخ أو الرقم المعتمد على locale داخل strings المترجمة.
+يجب أن يفتح عنصر التحكم "إعدادات الوكيل" علامة تبويب إعدادات الشريط الجانبي الصحيح للوكيل
+للنموذج، ومفتاح API، والتشغيل الآلي، والصوت، وعناصر التحكم الأخرى على مستوى إطار العمل.
+قد تقوم التطبيقات بتكرار إعدادات إطار العمل عالية القيمة في صفحة الإعدادات الخاصة بها
+عندما يكون الإعداد مركزيًا في التطبيق، ولكن تظل علامة تبويب إعدادات الشريط الجانبي هي
+مصدر الحقيقة.
+
+استخدم `useFormatters()` للتواريخ والأرقام والوقت النسبي والقوائم. لا تضع
+تنسيق التاريخ/الأرقام الحساس للإعدادات المحلية داخل سلاسل الترجمة.
 
-## محتوى موقع docs {#docs-site-content}
+## محتوى موقع المستندات {#docs-site-content}
 
-تستخدم صفحات docs العامة نفس core provider، لكن مع `persistPreference={false}` حتى يستخدم زوار docs المجهولون localStorage ولغة المتصفح بدلاً من SQL settings actions. يبقى مصدر English في `packages/core/docs/content/*.md`. توجد overrides المترجمة في `packages/core/docs/content/locales/<locale>/<slug>.md`.
+تستخدم صفحات المستندات العامة نفس الموفر الأساسي، ولكن مع
+`persistPreference={false}` لذلك تستخدم حركة مرور المستندات المجهولة localStorage و
+لغة المتصفح بدلاً من إعدادات SQL actions. يبقى المصدر الإنجليزي في
+`packages/core/docs/content/*.md`. يتم بث تجاوزات الصفحة المترجمة بجوارها ضمن
+`packages/core/docs/content/locales/<locale>/<slug>.md`.
 
-استخدم نفس BCP-47 locale codes الخاصة بكتالوجات التطبيقات. حافظ على نفس slug الموجود في مصدر English، واحفظ anchors ثابتة باستخدام `{#anchor}` على headings المترجمة، ولا تترجم routes أو action names أو protocol fields أو env vars أو provider names. إذا لم يملك locale ملف Markdown مترجماً لصفحة ما، يعود موقع docs إلى English لتلك الصفحة مع استمرار تعريب navigation و chrome.
+استخدم نفس الرموز المحلية BCP-47 مثل كتالوجات التطبيقات. احتفظ بنفس سبيكة
+مصدر باللغة الإنجليزية، حافظ على نقاط الارتساء الثابتة باستخدام `{#anchor}` في العناوين المترجمة،
+وترك المسارات وأسماء الإجراءات وحقول البروتوكول ومتغيرات env وأسماء الموفرين
+غير مترجم. إذا لم تكن اللغة تحتوي على Markdown مترجمة لصفحة ما، فإن موقع المستندات
+يعود إلى اللغة الإنجليزية لتلك الصفحة مع الاستمرار في ترجمة التنقل وchrome.
 
-## Actions والاستمرارية {#actions-and-persistence}
+## Actions والإصرار
 
-كل تطبيق يرث:
+يرث كل تطبيق:
 
-- `get-localization-preference` — يقرأ `{ locale }` للمستخدم الحالي
-- `set-localization-preference` — يضبط `"system"` أو locale مدعوماً
+- `get-localization-preference` - اقرأ `{ locale }` للمستخدم الحالي
+- `set-localization-preference` - قم بتعيين `"system"` أو لغة محلية مدعومة
 
-القيمة الدائمة موجودة في SQL settings بنطاق المستخدم تحت `localization`. يستخدم `localStorage` فقط قبل hydration وللرجوع المجهول. ينعكس locale النشط في application state كسياق محيط حتى تتمكن agents من رؤية لغة الواجهة الحالية.
+تتواجد القيمة الدائمة في إعدادات SQL على نطاق المستخدم ضمن `localization`.
+يستخدم `localStorage` فقط للترطيب المسبق والاحتياطي المجهول. النشط
+يتم عكس اللغة المحلية في حالة التطبيق كسياق محيط حتى يتمكن الوكلاء من رؤيتها
+لغة الواجهة الحالية.
 
-## Guard {#guard}
+## حارس
 
-شغّل:
+تشغيل:
 
 ```bash
 pnpm guard:i18n-catalogs
 ```
 
-يتحقق guard من أسماء ملفات locale المدعومة، و key parity، و placeholder parity، و stale keys، وفئات CLDR plural عبر `Intl.PluralRules`. هو يتحقق من البنية لا جودة الترجمة؛ strings البارزة ما زالت تحتاج مراجعة بشرية.
+يتحقق الحارس من أسماء الملفات المحلية المدعومة، وتكافؤ المفاتيح، وتكافؤ العناصر النائبة،
+المفاتيح القديمة، وفئات الجمع CLDR من خلال `Intl.PluralRules`. يقوم بالفحص
+البنية، وليس جودة الترجمة؛ لا تزال السلاسل عالية الوضوح بحاجة إلى الإنسان
+مراجعة.
 
-لا تترجم المعرفات الثابتة مثل action names أو routes أو enum values أو app-state keys أو database values أو protocol fields أو env var names أو provider names.
+لا تترجم المعرفات الثابتة مثل أسماء الإجراءات والمسارات وقيم التعداد
+مفاتيح حالة التطبيق، أو قيم قاعدة البيانات، أو حقول البروتوكول، أو أسماء env var، أو الموفر
+الأسماء.