@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ar-SA/native-chat-ui.md

@@ -0,0 +1,321 @@
+---
+title: "الدردشة الأصلية UI"
+description: "برامج عرض الدردشة الأصلية المعلنة عن إجراء، ومخرجات DataTable/DataChart القابلة لإعادة الاستخدام، وكيف يجب أن تتصل أوقات تشغيل وكيل BYO بدردشة Agent-Native."
+---
+
+# الدردشة الأصلية UI
+
+الدردشة الأصلية UI هي مسار العرض داخل التطبيق لمخرجات وكيل الطرف الأول.
+يرجع الإجراء JSON منظمًا، ويتعرف وقت تشغيل الدردشة على عنصر واجهة المستخدم الصريح
+المميز، ويعرض `<AssistantChat>` مكون React حقيقي في
+محادثة. لا يمكنك إنشاء إطار iframe أو قطعة أثرية HTML لمرة واحدة لـ
+دردشة التطبيق العادية.
+
+استخدم الدردشة الأصلية UI عندما يتعين على المستخدم فحص المخرجات حيث يوجد الوكيل
+أتحدث بالفعل: نتائج الاستعلام، ورؤى الاستجابة، وملخصات الإعداد،
+عناصر التحكم في الموافقة/الرفض، أو الروابط إلى طرق عرض التطبيق. استخدم [MCP Apps](/docs/mcp-apps)
+عندما يجب عرض مضيف خارجي مثل Claude أو ChatGPT أو Copilot أو Cursor
+مسار مضمّن من تطبيقك.
+
+```an-diagram title="The native render path" summary="An action returns JSON; the runtime matches an explicit widget discriminant or chatUI.renderer; AssistantChat mounts a real React component. No iframe, no HTML execution."
+{
+  "html": "<div class=\"diagram-render\"><div class=\"diagram-node\">Action runs<br><small class=\"diagram-muted\">returns structured JSON</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Match</span><small class=\"diagram-muted\">explicit widget &middot; chatUI.renderer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">&lt;AssistantChat&gt;<br><small class=\"diagram-muted\">mounts a React widget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill ok\">DataTable</div><div class=\"diagram-pill ok\">DataChart</div><div class=\"diagram-pill ok\">DataInsights</div></div></div>",
+  "css": ".diagram-render{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-render .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-render .col{display:flex;flex-direction:column;gap:6px;padding:12px}.diagram-render .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## الأدوات المصغّرة للإجراء {#action-declared-widgets}
+
+يتكون المسار الأصلي من جزأين واضحين:
+
+- يقوم `outputSchema` بالتحقق من صحة شكل استجابة الإجراء.
+- يحدد `chatUI.renderer` عارض React الأصلي للنتيجة التي تم التحقق من صحتها.
+
+تستخدم أجهزة عرض البيانات المضمنة نتيجة JSON عادية مع `widget` بالإضافة إلى
+الحمولة المطابقة:
+
+| القطعة            | الحمولة المطلوبة           | يتم عرضه كـ                                 |
+| ----------------- | -------------------------- | ------------------------------------------- |
+| `"data-table"`    | `table`                    | جدول بيانات أصلي وقابل لإعادة الاستخدام     |
+| `"data-chart"`    | `chartSeries`              | مخطط شريطي أو خطي أو مساحي أصلي             |
+| `"data-insights"` | `table` و/أو `chartSeries` | بطاقة معلومات مدمجة مع مخرجات المخطط/الجدول |
+
+يجب على الخادم actions استيراد المخططات والمساعدات الآمنة للخادم من
+`@agent-native/core/data-widgets`; client code can import the same types from
+`@agent-native/core/client/chat` أو `@agent-native/core/client`.
+
+```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
+import {
+  createDataInsightsWidgetResult,
+  dataInsightsWidgetResultSchema,
+} from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Analyze form responses.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+    title: "Response insights",
+  },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response insights",
+      display: {
+        title: "42 responses",
+        description: "Completion rate rose this week.",
+        primaryAction: {
+          label: "Open response insights",
+          href: "/response-insights",
+        },
+      },
+      chartSeries: {
+        type: "bar",
+        title: "Responses by day",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 8 },
+          { day: "Tue", responses: 13 },
+        ],
+      },
+      table: {
+        title: "Top answers",
+        columns: [
+          { key: "answer", label: "Answer" },
+          { key: "count", label: "Count", align: "right" },
+        ],
+        rows: [
+          { answer: "Yes", count: 31 },
+          { answer: "No", count: 11 },
+        ],
+        totalRows: 2,
+      },
+    }),
+});
+```
+
+```an-callout
+{
+  "tone": "success",
+  "body": "The renderer only takes over when the action declares `chatUI` **or** the result carries an explicit known `widget` discriminant. It never shape-infers arbitrary objects and never executes HTML or JavaScript from tool results — so a native widget can't become an injection vector."
+}
+```
+
+عندما يطلب المستخدم مخططًا أو رسمًا بيانيًا أو جدولًا أو اتجاهًا أو تقريرًا مضغوطًا، فإن وكلاء التطبيق
+الإجراء الذي يعلن عن أحد هؤلاء العارضين الأصليين. النهائي
+يجب أن يظل النص المساعد مختصرًا ويسمح للأداة بحمل البيانات؛ لا تنسخ
+نفس الصفوف في جدول تخفيض السعر ما لم يطلب المستخدم نصًا صراحةً
+تصدير.
+
+في حالة عدم وجود إجراء مجال ولكن الوكيل قد قام بالفعل باسترداد مضغوط،
+بيانات صادقة، يمكنها استدعاء الإجراء `render-data-widget` لإطار العمل باستخدام
+نفس شكل `data-table` أو `data-chart` أو `data-insights` JSON. هذا الإجراء فقط
+يقوم بالتحقق من صحة الأداة وعرضها؛ إنه ليس مصدر بيانات ويجب عدم استخدامه
+لاختراع مقاييس العنصر النائب.
+
+## إخراج DataTable {#data-table}
+
+إن `table` بسيط عن عمد، لذلك يمكن إدراج SQL والتحليلات وإعداد actions
+إعادة استخدامه:
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+تفضل مفاتيح الأعمدة الثابتة وقيم الصفوف الآمنة JSON. استخدم `totalRows`،
+`sampledRows`، و`truncated` عندما يعرض الإجراء شريحة أكبر
+مجموعة النتائج.
+
+## إخراج مخطط البيانات {#data-chart}
+
+يدعم `chartSeries` أشكال المخططات الشائعة المستخدمة في إجابات الوكيل بدون
+مطالبة كل قالب بإرسال عارض الدردشة الخاص به:
+
+```ts
+{
+  type: "bar" | "line" | "area";
+  title?: string;
+  xKey: string;
+  series: Array<{ key: string; label: string; color?: string }>;
+  data: Array<Record<string, unknown>>;
+  sampled?: boolean;
+}
+```
+
+حافظ على ضغط بيانات المخطط. بالنسبة لمجموعات البيانات الكبيرة، قم بتجميعها في الإجراء والارتباط
+إلى العرض الكامل للتطبيق باستخدام البيانات التعريفية `display.primaryAction` أو الإجراء `link`.
+
+## الأدوات الأصلية مقابل تطبيقات MCP {#native-vs-mcp-apps}
+
+أدوات الدردشة الأصلية وتطبيقات MCP متكاملة:
+
+- **الأدوات الأصلية** مخصصة لوقت تشغيل الدردشة الخاص بالتطبيق. نتيجة الإجراء هي
+  JSON، ويعرض إطار العمل عنصر واجهة المستخدم React المدمج.
+- **تطبيقات MCP** مخصصة للمضيفين الخارجيين. يعلن الإجراء `mcpApp` وعادةً
+  `link`، ويعرض المضيف مسارًا حقيقيًا للتطبيق مضمنًا عند دعمه.
+- **تظل الروابط العميقة** بمثابة البديل العام. استخدم الإجراء `link` أو
+  `display.primaryAction`، عملاء CLI، ومضيفو MCP الأقدم، والنص العادي
+  يمكن للقراء فتح عرض التطبيق الكامل.
+
+عند وجود كل من حمولة عنصر واجهة المستخدم الأصلية والبيانات التعريفية لتطبيقات MCP، يظهر داخل التطبيق
+تفضل الدردشة الأداة الأصلية. يستخدم المضيفون الخارجيون مورد MCP Apps أو
+ارتباط احتياطي عميق.
+
+## برامج العرض الأصلية المخصصة {#custom-native-renderers}
+
+قم بتسجيل المكونات الخاصة بالمنتج حسب معرف العارض الدقيق، ثم أعلن عن هذا المعرف
+في الإجراء:
+
+```tsx
+import { registerActionChatRenderer } from "@agent-native/core/client/chat";
+
+registerActionChatRenderer({
+  id: "crm.deal-card",
+  renderer: "crm.deal-card",
+  Component: ({ context }) => <DealCard result={context.resultJson} />,
+});
+```
+
+```ts
+export default defineAction({
+  description: "Show a deal card.",
+  outputSchema: dealCardSchema,
+  chatUI: { renderer: "crm.deal-card" },
+  run: async () => ({ dealId: "deal_123", amount: 42000 }),
+});
+```
+
+استخدم هذا مع تطبيق الطرف الأول UI. احتفظ بإطار iframe UI للمضيف المشترك في `mcpApp`، واحتفظ
+تنفيذ استعلام عشوائي خلف قراءة actions المكتوبة بدلاً من SQL الأولية في الدردشة.
+
+## أوقات تشغيل الوكيل BYO {#byo-agent-runtimes}
+
+`AgentChatRuntime` هو عقد إحضار الوكيل الخاص بك لقشرة الدردشة، و
+هذا القسم هو مرجعه الأساسي. فهو يتيح للوكيل الذي أنشأته في مكان آخر
+بث الأحداث التي تمت تسويتها في محادثة Agent-Native UI مع الاحتفاظ بـ
+المؤلف المشترك، وعرض النص، وبطاقات الأدوات، والموافقات، والأدوات الأصلية،
+وتخطيط التطبيق المحيط. [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+نقاط تعليمية هنا لقصة وقت التشغيل، و[Component API](/docs/components#agent-chat-ui)
+يسرد كل موصل ومحول مع مسار الاستيراد الخاص به؛ العقد نفسه هو
+موضح أدناه.
+
+```an-diagram title="BYO runtime keeps the Agent-Native chat shell" summary="Your external agent streams normalized events through a connector; Agent-Native keeps the composer, transcript, tool cards, approvals, and native widgets."
+{
+  "html": "<div class=\"diagram-byo\"><div class=\"diagram-box\" data-rough>Your agent<br><small class=\"diagram-muted\">OpenAI &middot; Claude &middot; Vercel AI &middot; AG-UI &middot; HTTP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">connector</span><small class=\"diagram-muted\">normalized message-* / tool-* events</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill\">&lt;AssistantChat runtime=&hellip; /&gt;</div><small class=\"diagram-muted\">composer &middot; transcript &middot; tool cards</small><small class=\"diagram-muted\">approvals &middot; native widgets</small></div></div>",
+  "css": ".diagram-byo{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-byo .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-byo .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-byo .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+يتم تصدير كافة الموصلات من `@agent-native/core/client/chat` (والجذر
+إدخال `@agent-native/core/client`). استخدم وقت التشغيل HTTP العام عندما يكون وكيلك
+يمكن أن يعرض نقطة نهاية POST التي تُرجع أحداث وقت التشغيل SSE أو NDJSON:
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:mastra",
+  label: "Mastra",
+  endpoint: "/api/mastra/chat",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAgentToken()}`,
+  }),
+});
+
+export function SupportChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+إذا كانت نقطة النهاية لديك تقوم بالفعل ببث بروتوكول وكيل مشترك، فاستخدم المطابقة
+الموصل وتخطي كتابة مخطط مخصص:
+
+```ts
+import {
+  createAgUiChatRuntime,
+  createClaudeAgentChatRuntime,
+  createOpenAIAgentsChatRuntime,
+  createOpenAIResponsesChatRuntime,
+  createVercelAiChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const openAiAgentsRuntime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/openai-agents/chat",
+});
+
+const openAiResponsesRuntime = createOpenAIResponsesChatRuntime({
+  endpoint: "/api/openai-responses/chat",
+});
+
+const claudeAgentRuntime = createClaudeAgentChatRuntime({
+  endpoint: "/api/claude-agent/chat",
+});
+
+const vercelAiRuntime = createVercelAiChatRuntime({
+  endpoint: "/api/vercel-ai/chat",
+});
+
+const agUiRuntime = createAgUiChatRuntime({
+  endpoint: "/api/ag-ui/chat",
+});
+```
+
+قد تقوم نقطة النهاية ببث شكل الحدث المقيس مباشرة:
+
+```text
+data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+بالنسبة للوكلاء البسيطين جدًا، يتم قبول استجابة JSON `{ "text": "..." }` و
+تم تحويلها إلى رسالة مساعد واحدة. بالنسبة للعملاء الأكثر ثراءً، قم بالبث
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+أحداث `usage` و`error` و`done`. يمكن أن تحمل نتائج الأداة `mcpApp` أو
+البيانات التعريفية `chatUI`، لذلك لا تزال عناصر واجهة المستخدم الأصلية المعلنة عن الإجراء يتم عرضها بدون
+إطارات iframe.
+
+عندما تريد نقل Agent-Native المدمج ككائن وقت التشغيل، استخدم:
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+استخدم `<AssistantChat createAdapter={...} />` فقط عندما تحتاج إلى استخدام كامل
+التحكم في محول واجهة المستخدم المساعد. استخدم `PromptComposer` بمفرده عندما يكون منتجك
+يمتلك النص الخارجي بالكامل ويريد فقط مؤلف Agent-Native
+الحقل.
+
+يمكن لتدفقات OpenAI وAG-UI وClaude Agent SDK وVercel AI SDK استخدام المعيار
+مساعدو الموصل. يظل ACP قابلية التشغيل التفاعلي لعامل الترميز/المحرر، وليس
+وقت التشغيل العام للدردشة التطبيقية للمستخدمين النهائيين. لم تتم المطالبة بـ A2UI على أنه مدعوم هنا؛
+إذا نضجت، فيجب أن تتكيف مع نفس العقد الصريح لوقت التشغيل/الأداة.
+
+## المستندات ذات الصلة {#related-docs}
+
+- [Actions](/docs/actions) — حدد العمليات التي تُرجع بيانات عنصر واجهة المستخدم الأصلية.
+- [Agent Surfaces](/docs/agent-surfaces) - حدد ما إذا كنت بحاجة إلى التطبيق بدون رأس، أو الدردشة، أو السيارة الجانبية، أو التطبيق الكامل.
+- [Drop-in Agent](/docs/drop-in-agent) — البرنامج التعليمي لتثبيت وقت التشغيل القياسي للدردشة.
+- [Component API](/docs/components) — خريطة API لكل عملية تصدير لطبقات الدردشة، وأوقات التشغيل، وعارضي الأدوات.
+- [MCP Apps](/docs/mcp-apps) — UI المضمّن لمضيفي MCP الخارجيين.
+- [Key Concepts](/docs/key-concepts#protocols) — حالة البروتوكول وتحديد المواقع.

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

@@ -0,0 +1,231 @@
+---
+title: "الإشعارات"
+description: "إشعارات داخل التطبيق مع قنوات قابلة للتوصيل — البريد الوارد، أو الرد التلقائي على الويب، أو القنوات المخصصة"
+---
+
+# الإشعارات
+
+وظيفة واحدة، وجهات متعددة. اتصل بـ `notify()` من أي رمز من جانب الخادم - إجراء، أو أتمتة، أو مكون إضافي - وسيصل الحدث إلى صندوق الوارد داخل التطبيق الخاص بالمستخدم وينتشر في كل قناة مسجلة. يأتي مزودًا بمكون الجرس والقائمة المنسدلة UI الذي يسقطه القالب المضيف في رأسه.
+
+الإشعارات عبارة عن تنبيهات أحادية الاتجاه تصل إلى صندوق بريد الجرس الخاص بالتطبيق (بالإضافة إلى نشر خطاف الويب). للتحدث مع وكيلك من Slack/email/Telegram/WhatsApp، راجع [Messaging](/docs/messaging).
+
+```ts
+import { notify } from "@agent-native/core/notifications";
+
+await notify(
+  { severity: "info", title: "Booking confirmed", body: "Jane at 3pm" },
+  { owner: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One call, many destinations" summary="notify() always writes the owner-scoped inbox row, fans out to every registered channel in parallel (best-effort), then emits notification.sent on the event bus."
+{
+  "html": "<div class=\"diagram-notify\"><div class=\"diagram-node\">notify(input, { owner })<br><small class=\"diagram-muted\">any server code &middot; action, automation, plugin</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel fan\" data-rough><div class=\"fan-row\"><span class=\"diagram-pill accent\">inbox</span><div class=\"diagram-box\" data-rough>notifications table &rarr; bell UI<br><small class=\"diagram-muted\">always on &middot; owner-scoped</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">webhook</span><div class=\"diagram-box\" data-rough>POST JSON to NOTIFICATIONS_WEBHOOK_URL<br><small class=\"diagram-muted\">best-effort</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">custom</span><div class=\"diagram-box\" data-rough>registerNotificationChannel(...)<br><small class=\"diagram-muted\">best-effort &middot; runs in parallel</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">notification.sent</span><small class=\"diagram-muted\">event bus &middot; automations can chain</small></div></div>",
+  "css": ".diagram-notify{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-notify .fan{display:flex;flex-direction:column;gap:10px;padding:14px}.diagram-notify .fan-row{display:flex;align-items:center;gap:10px}.diagram-notify .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-notify .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## الشدة {#severities}
+
+| الخطورة    | يستخدم لـ                                |
+| ---------- | ---------------------------------------- |
+| `info`     | التأكيدات، معالم التقدم، FYI             |
+| `warning`  | شيء يجب على المستخدم الاطلاع عليه قريبًا |
+| `critical` | يحتاج إلى اهتمام فوري                    |
+
+تؤدي درجة الخطورة إلى تحديد نمط الشارة في القائمة المنسدلة ويتم تمريرها عبر القنوات حتى تتمكن من التفرع عند الحاجة الملحة.
+
+## القنوات المدمجة {#channels}
+
+| القناة    | التسليم                                            | يتطلب                                                         |
+| --------- | -------------------------------------------------- | ------------------------------------------------------------- |
+| `inbox`   | الاستمرار في الجدول `notifications`؛ يحرك الجرس UI | تشغيل دائمًا — جزء من البدائي.                                |
+| `webhook` | POST JSON إلى URL التي تم تكوينها                  | تم تعيين `NOTIFICATIONS_WEBHOOK_URL` env var عند بدء التشغيل. |
+
+تعمل قناة webhook على حل مراجع `${keys.NAME}` في كل من URL و`NOTIFICATIONS_WEBHOOK_AUTH` مقابل [secrets](/docs/security) المخصص للمالك، لذلك لا تدخل القيمة الأولية مطلقًا في سياق الوكيل. يتم فرض قوائم URL المسموح بها لكل مفتاح - نفس القاعدة التي تستخدمها أداة `web-request` للتشغيل الآلي.
+
+```an-diagram title="Channels and severity" summary="inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."
+{
+  "html": "<div class=\"diagram-channels\"><div class=\"diagram-panel col\" data-rough><strong>Channels</strong><div class=\"diagram-box\" data-rough>inbox<br><small class=\"diagram-muted\">always on &mdash; part of the primitive</small></div><div class=\"diagram-box\" data-rough>webhook<br><small class=\"diagram-muted\">needs NOTIFICATIONS_WEBHOOK_URL</small></div><div class=\"diagram-box\" data-rough>custom<br><small class=\"diagram-muted\">registerNotificationChannel()</small></div></div><div class=\"diagram-panel col\" data-rough><strong>Severity drives the badge</strong><div class=\"sev-row\"><span class=\"diagram-pill\">info</span><span class=\"diagram-muted\">confirmations, FYI</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">warning</span><span class=\"diagram-muted\">look at soon</span></div><div class=\"sev-row\"><span class=\"diagram-pill accent\">critical</span><span class=\"diagram-muted\">needs immediate attention</span></div></div></div>",
+  "css": ".diagram-channels{display:flex;gap:16px;flex-wrap:wrap;align-items:flex-start}.diagram-channels .col{display:flex;flex-direction:column;gap:10px;padding:14px;min-width:240px}.diagram-channels .sev-row{display:flex;align-items:center;gap:10px}"
+}
+```
+
+## API {#api}
+
+### `notify(input, meta)` {#notify}
+
+تسليم إشعار. يستمر دائمًا في البريد الوارد ما لم يتم استبعاده بشكل صريح؛ يتم تشغيل القنوات المسجلة الإضافية بالتوازي وبأفضل جهد.
+
+```ts
+await notify(
+  {
+    severity: "critical",
+    title: "Database offline",
+    body: "Primary dropped connections",
+    metadata: { runbookUrl: "https://runbooks/db-offline" },
+    channels: ["inbox", "webhook"], // optional allowlist; omit to run all
+  },
+  { owner: "ops@company.com" },
+);
+```
+
+مطلوب `meta.owner` — لتحديد نطاق الإشعار بحيث يراه المستخدم فقط في الجرس.
+
+### `registerNotificationChannel(channel)` {#register}
+
+قم بتسجيل قناة مخصصة من أي مكون إضافي للخادم.
+
+```ts
+import { registerNotificationChannel } from "@agent-native/core/notifications";
+
+registerNotificationChannel({
+  name: "slack-ops",
+  async deliver(input, meta) {
+    await fetch(process.env.OPS_SLACK_WEBHOOK!, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `*${input.severity.toUpperCase()}* — ${input.title}\n${input.body ?? ""}`,
+        owner: meta.owner,
+      }),
+    });
+  },
+});
+```
+
+أسماء القنوات فريدة من نوعها — حيث تؤدي إعادة التسجيل إلى استبدال القناة السابقة. `deliver()` هو أفضل جهد؛ يؤدي الرمي إلى تسجيل الخطأ ولكنه لا يحظر القنوات الأخرى أو صف البريد الوارد.
+
+### الإدراج والقراءة {#read}
+
+```ts
+import {
+  listNotifications,
+  countUnread,
+  markNotificationRead,
+  markAllNotificationsRead,
+  deleteNotification,
+} from "@agent-native/core/notifications";
+
+const rows = await listNotifications("steve@builder.io", {
+  unreadOnly: true,
+  limit: 50,
+});
+const unread = await countUnread("steve@builder.io");
+await markNotificationRead(rows[0].id, "steve@builder.io");
+await markAllNotificationsRead("steve@builder.io");
+await deleteNotification(rows[0].id, "steve@builder.io");
+```
+
+تقع كل وظيفة على نطاق المالك - لا توجد عمليات قراءة بين المستخدمين، ولا توجد عمليات كتابة بين المستخدمين.
+
+## واجهة NotificationChannel {#channel-interface}
+
+```ts
+interface NotificationChannel {
+  name: string;
+  deliver(
+    input: NotificationInput,
+    meta: NotificationMeta,
+  ): void | Promise<void>;
+}
+
+interface NotificationInput {
+  severity: "info" | "warning" | "critical";
+  title: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  channels?: string[];
+}
+
+interface NotificationMeta {
+  owner: string;
+}
+```
+
+## HTTP API {#http}
+
+تم تركيبه على `/_agent-native/notifications/*` بواسطة البرنامج الإضافي للمسارات الأساسية. يتم تحديد نطاق كافة المسارات إلى البريد الإلكتروني للجلسة التي تمت مصادقتها.
+
+| الطريقة  | المسار                                              |
+| -------- | --------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
+| `GET`    | `/_agent-native/notifications/count`                |
+| `POST`   | `/_agent-native/notifications/:id/read`             |
+| `POST`   | `/_agent-native/notifications/read-all`             |
+| `DELETE` | `/_agent-native/notifications/:id`                  |
+
+```an-api title="List notifications" summary="The route behind listNotifications() — scoped to the authenticated session's email."
+{
+  "method": "GET",
+  "path": "/_agent-native/notifications?unread=true&limit=50",
+  "summary": "List recent notifications for the current user",
+  "auth": "Authenticated session; results are scoped to the session's email.",
+  "params": [
+    { "name": "unread", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only unread notifications." },
+    { "name": "limit", "in": "query", "type": "number", "required": false, "description": "Max rows to return." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Owner-scoped notification rows, newest first." }
+  ]
+}
+```
+
+## مكون UI {#ui}
+
+```tsx
+import { NotificationsBell } from "@agent-native/core/client/notifications";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <NotificationsBell browserNotifications />
+    </header>
+  );
+}
+```
+
+رمز الجرس مع شارة غير مقروءة. يؤدي النقر إلى فتح قائمة منسدلة للإشعارات الحديثة. يستخدم الرموز الدلالية shadcn، ويتكيف مع المظهر الفاتح/الغامق للقالب المضيف.
+
+قم بتمرير `browserNotifications` لإطلاق النوافذ المنبثقة `new Notification(...)` للنظام أيضًا لكل عنصر جديد غير مقروء - وهو أمر مفيد عندما تكون علامة تبويب المستخدم في الخلفية. تعرض القائمة المنسدلة رسالة "تمكين" حتى يمنح المستخدم الإذن؛ يتم منع التكرارات لكل معرف عبر حقل الإشعار `tag`.
+
+## أدوات الوكيل {#agent-tools}
+
+يتم تسجيل أداة `manage-notifications` واحدة في كل قالب. تحدد المعلمة `action` العملية:
+
+| الإجراء | المعلمات                                                                | الغرض                                                   |
+| ------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
+| `send`  | `severity` (مطلوب)، `title` (مطلوب)، `body`، `metadataJson`، `channels` | إرسال إشعار إلى البريد الوارد للمستخدم والقنوات المسجلة |
+| `list`  | `unreadOnly`، `limit` (الحد الأقصى 200، الافتراضي 20)                   | أدرج الإشعارات الأخيرة للسياق                           |
+
+يمكن للأتمتة (راجع [Automations](/docs/automations)) استدعاء `manage-notifications` مع وجود `action=send` في نصها — وهذا هو النمط المتعارف عليه لتحويل حدث خارجي إلى تنبيه مرئي للمستخدم.
+
+## حافلة الأحداث {#event-bus}
+
+كل تسليم ناجح يصدر `notification.sent` على [event bus](/docs/automations#event-bus):
+
+```json
+{
+  "notificationId": "n-123",
+  "severity": "critical",
+  "title": "DB offline",
+  "body": "Primary dropped connections",
+  "deliveredChannels": ["inbox", "webhook"]
+}
+```
+
+يمكن للأتمتة أن تقوم بتسلسل هذا — على سبيل المثال. _"إذا تم إطلاق إشعار مهم، قم أيضًا بالصفحة عند الطلب."_
+
+## كيفية العمل {#internals}
+
+- **نطاق المالك** — يحتوي كل صف على عمود `owner`؛ يتم تصفية كل استعلام عليه؛ يستخدم كل مسار البريد الإلكتروني للجلسة المصادق عليها. لا يرى المستخدمون أبدًا إشعارات بعضهم البعض.
+- **تكامل الاستقصاء** — تستدعي كل طفرة `recordChange()`، لذا يتم إبطال صحة القوالب التي تستخدم [`useDbSync`](/docs/client) تلقائيًا دون أي أسلاك إضافية.
+- **توزيع أفضل جهد** — يتم اكتشاف أخطاء القناة وتسجيلها؛ لا تؤدي إحدى القنوات الفاشلة إلى منع القنوات الأخرى أو الكتابة في البريد الوارد.
+- **أطلق النار وانسى** — يعود `notify()` بعد اكتمال الكتابة في البريد الوارد؛ تعمل القنوات المخصصة في الخلفية.
+
+## ما هي الخطوة التالية
+
+- [**Automations**](/docs/automations) — المتصل الأكثر شيوعًا في `notify()`
+- [**Security**](/docs/security) — استبدال `${keys.NAME}` الذي يعمل على تشغيل قناة الويب هوك
+- [**Server plugins**](/docs/server) — حيث يتم تسجيل القنوات المخصصة عند بدء التشغيل