@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,106 @@
+---
+title: "المعالجات داخل الحلقة"
+description: "حلقة المراقبة الداخلية/خطافات الدرابزين التي تراقب مخرجات النموذج المتدفقة واستدعاءات الأداة في منتصف التشغيل ويمكن أن تلغيها - خط التماس لحواجز الحماية في الوقت الفعلي وبوابات إثبات التنفيذ."
+---
+
+# المعالجات داخل الحلقة
+
+`Processor` عبارة عن حلقة داخلية **مراقب/حاجز حماية** لتشغيل الوكيل. فهو يراقب إخراج النموذج المتدفق وتستدعيه الأداة طلبات _مع تقدم التشغيل_، ويحتفظ بحالة التسويد الخاصة به، ويمكنه **إجهاض** التشغيل قبل المطالبة بـ "تم". هذا هو الشرط الهيكلي الأساسي لحواجز الحماية في الوقت الفعلي (حظر الإخراج غير المسموح به في منتصف الدفق) وبوابة إثبات التنفيذ/التغطية (فحص ما على وشك القيام به النموذج وإيقافه).
+
+```an-diagram title="Where the three hooks fire in the run" summary="processOutputStream watches every chunk, processOutputStep gates tool calls per response, processOutputResult records a verdict at the end. Any hook can abort with a TripWire."
+{
+  "html": "<div class=\"diagram-proc\"><div class=\"diagram-node\" data-rough>stream chunks<br><small class=\"diagram-muted\">processOutputStream</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>per model response<br><small class=\"diagram-muted\">processOutputStep — gate tool calls</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\" data-rough>run end<br><small class=\"diagram-muted\">processOutputResult — verdict</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-pill warn\">abort() &rarr; TripWire &rarr; tripwire event</div></div>",
+  "css": ".diagram-proc{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-proc .diagram-arrow{font-size:22px;line-height:1}.diagram-proc .diagram-pill{flex-basis:100%}"
+}
+```
+
+> [!WARNING]
+> المعالج هو **تكوين**، وليس أداة، وليس إجراءً، وليس تأليفًا DSL. تقوم المعالجات فقط بمراقبة وتعديل حالة نطاق الدفق الخاصة بها و`abort()`. ولا تحدد أبدًا سلوك التطبيق، أو تستبدل actions، أو تظهر للنموذج. تنتمي عمليات التطبيق إلى [actions](/docs/actions).
+
+## الخطافات {#hooks}
+
+ينفذ المعالج أي مجموعة فرعية من ثلاثة خطافات دورة حياة اختيارية (الشكل مستعار من معالجات إخراج Mastra):
+
+| خطاف                  | الحرائق...                                            | استخدمه من أجل...                                            |
+| --------------------- | ----------------------------------------------------- | ------------------------------------------------------------ |
+| `processOutputStream` | لكل جزء متدفق (دلتا النص/التفكير) أثناء إنشاء النموذج | رد على الإخراج قبل أن يهبط المنعطف الكامل                    |
+| `processOutputStep`   | مرة واحدة لكل استجابة نموذج، أثناء تنفيذ الأداة       | فحص استدعاءات الأداة للنموذج الذي على وشك التشغيل؛ بوابة لهم |
+| `processOutputResult` | مرة واحدة عند نهاية التشغيل، مع النص المساعد الأخير   | سجل حكمًا/إثباتًا للإجابة المكتملة                           |
+
+يحصل كل معالج على كائن `state` القابل للتغيير ونطاق التشغيل والذي يستمر عبر كل واحد من استدعاءات الخطاف الخاصة به في عملية تشغيل واحدة و**معزول\*\*** عن حالة المعالجات الأخرى.
+
+```ts
+import type { Processor } from "@agent-native/core";
+
+const noSecretsInOutput: Processor = {
+  name: "no-secrets",
+  processOutputStream({ part, abort }) {
+    if (part.type === "text" && /sk-live_/.test(part.text)) {
+      abort("Model attempted to emit a live secret token.", {
+        kind: "secret-leak",
+      });
+    }
+  },
+};
+
+const coverageGate: Processor = {
+  name: "proof-of-done",
+  processOutputStep({ toolCalls, state }) {
+    // Track what the model has actually done this run...
+    for (const call of toolCalls) {
+      (state.ran ??= new Set<string>()).add(call.name);
+    }
+  },
+  processOutputResult({ text, state }) {
+    // ...and record a verdict over the final answer.
+    const ran = state.ran as Set<string> | undefined;
+    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
+  },
+};
+```
+
+## الإجهاض باستخدام `TripWire` {#tripwire}
+
+يقوم الخطاف بإيقاف التشغيل عن طريق استدعاء `abort(reason, meta?)`، مما يؤدي إلى ظهور **`TripWire`**. تلتقطه الحلقة، وترسل **حدث `tripwire`** واحدًا، وتتوقف بشكل واضح، وتظهر السبب كرسالة مساعدة نهائية.
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+يحتوي الحدث `tripwire` على:
+
+| الحقل       | اكتب     | ملاحظات                                                     |
+| ----------- | -------- | ----------------------------------------------------------- |
+| `reason`    | `string` | تم تمرير السبب الذي يمكن قراءته بواسطة الإنسان إلى `abort`. |
+| `processor` | `string` | اسم المعالج الذي تم إحباطه عندما أعلن عن `name`.            |
+
+يحمل `TripWire` أيضًا `meta` المنظم الاختياري واسم `processor` الأصلي للمستهلكين الآليين الذين يتحقق منهم `instanceof`. نظرًا لأن التوقف أمر سهل، فإن `processOutputResult` يستمر في تشغيل النص النهائي (المتوقف) حتى يتمكن معالج إثبات التنفيذ من تسجيل حكمه حتى عند إلغاء التشغيل.
+
+## معالجات الأسلاك {#wiring}
+
+يتم تكوين المعالجات في التعليمات البرمجية عبر مصفوفة `processors` على `runAgentLoop`:
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**الحمل الصفري عند عدم الاستخدام.** تقوم الحلقة ببناء سلسلة المعالج فقط عند توفير معالج واحد على الأقل؛ عند حذف `processors` أو تركه فارغًا، لن يتم تشغيل أي من أكواد التماس وتكون الحلقة بدون تغيير بايت مقابل بايت. تعمل الخطافات بترتيب التسجيل وقد تكون متزامنة أو غير متزامنة.
+
+> [!NOTE]
+> يعتبر التماس على مستوى الحلقة هو ما يمكن تسليمه اليوم ويمكن استدعاؤه مباشرة بواسطة الوكلاء الفرعيين، A2A، MCP، والاختبارات. يعد ربط `processors` من خلال معالج الدردشة HTTP (بحيث يمكن لمحلل كل طلب تهيئتها دون الاتصال بـ `runAgentLoop` مباشرة) بمثابة توصيلات ملائمة لم يتم توصيلها بعد - قم بتكوين المعالجات في موقع الاتصال `runAgentLoop` في الوقت الحالي.
+
+## ذات صلة
+
+- [**Durable Resume**](/docs/durable-resume) — كيف تتغلب الحلقة على الانقطاعات دون إعادة تشغيل التأثيرات الجانبية المكتملة.
+- [**Custom Agents & Teams**](/docs/agent-teams) — يقوم الوكلاء الفرعيون بتشغيل نفس الحلقة ويمكنهم حمل المعالجات الخاصة بهم.
+- [**Observability**](/docs/observability) — تسجيل قرارات المعالج جنبًا إلى جنب مع آثار التشغيل.

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

@@ -0,0 +1,199 @@
+---
+title: "التقدم"
+description: "إشارة تقدم مباشرة لمهام الوكيل طويلة الأمد - البدء والتحديث والإكمال"
+---
+
+# التقدم
+
+يجب ألا تختبئ مهام الوكيل الطويلة خلف القرص الدوار. يوفر `progress_runs` للوكيل طريقة للإعلان _"أنا أعمل على هذا، لقد انتهيت من 45%، إليك الخطوة الحالية"_ - والتي يعرضها UI كدرج تشغيل عائم مع شريط نسبة مئوية.
+
+```ts
+import {
+  startRun,
+  updateRunProgress,
+  completeRun,
+} from "@agent-native/core/progress";
+
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Triage 128 unread emails",
+  step: "Fetching inbox",
+});
+
+for (let i = 1; i <= total; i++) {
+  await updateRunProgress(run.id, run.owner, {
+    percent: Math.round((i / total) * 100),
+    step: `Classifying ${i}/${total}`,
+  });
+}
+
+await completeRun(run.id, run.owner, "succeeded");
+```
+
+قلق منفصل عن [notifications](/docs/notifications): يتم تشغيل الإشعارات مرة واحدة (_"حدث X"_)، والتقدم هو حالة مستمرة (_"تم الانتهاء من X بنسبة 45%"_). يقوم التأليفان — `completeRun` متبوعًا بـ `notify(..., severity: "info")` بإخبار المستخدم عند انتهاء العمل حتى لو لم يكن يشاهد الدرج.
+
+## دورة الحياة {#lifecycle}
+
+| الحالة      | الانتقال                           |
+| ----------- | ---------------------------------- |
+| `running`   | الأولي — تم ضبطه بواسطة `startRun` |
+| `succeeded` | محطة المسار السعيد                 |
+| `failed`    | خطأ في المحطة                      |
+| `cancelled` | تمت مقاطعة المستخدم                |
+
+```an-diagram title="Run lifecycle" summary="startRun opens a running row; updateRunProgress patches it; completeRun moves it to one terminal status and stamps completed_at."
+{
+  "html": "<div class=\"diagram-run\"><div class=\"diagram-box\" data-rough>startRun()</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel running\" data-rough><span class=\"diagram-pill accent\">running</span><small class=\"diagram-muted\">updateRunProgress() &#8635; percent + step</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col terminal\"><span class=\"diagram-pill ok\">succeeded</span><span class=\"diagram-pill warn\">failed</span><span class=\"diagram-pill\">cancelled</span><small class=\"diagram-muted\">completeRun() &rarr; sets completed_at</small></div></div>",
+  "css": ".diagram-run{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-run .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:12px 16px}.diagram-run .terminal{display:flex;flex-direction:column;gap:6px;align-items:flex-start}.diagram-run .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+تم ضبط الحالات الطرفية على `completed_at`. يعرض درج UI صفوف `running` فقط؛ تبقى الصفوف المكتملة في قاعدة البيانات لاستعلامات `action=list`.
+
+## API {#api}
+
+### `startRun(input)` {#start}
+
+إنشاء جولة. تقوم بإرجاع `AgentRun` الكامل بالمعرف الذي تم إنشاؤه.
+
+```ts
+const run = await startRun({
+  owner: "steve@builder.io",
+  title: "Ingest 1M rows",
+  step: "Opening CSV",
+  metadata: { jobId: "abc123", artifactPath: "s3://..." },
+});
+```
+
+ينبعث `run.progress.started` على ناقل الحدث.
+
+### `updateRunProgress(id, owner, input)` {#update}
+
+قم بتصحيح أي حقل للتشغيل الجاري. أي حقل محذوف يبقى دون تغيير.
+
+```ts
+await updateRunProgress(run.id, run.owner, {
+  percent: 75,
+  step: "Writing to target DB",
+});
+```
+
+ينبعث `run.progress.updated` على ناقل الحدث. إرجاع `AgentRun` المحدث، أو `null` إذا لم يكن التشغيل موجودًا أو لم يكن مملوكًا للمتصل.
+
+### `completeRun(id, owner, status, extras?)` {#complete}
+
+الانتقال إلى حالة المحطة الطرفية. `succeeded` يعين ضمنيًا `percent=100`.
+
+```ts
+await completeRun(run.id, run.owner, "succeeded", {
+  step: "All 1M rows ingested",
+  metadata: { totalDurationMs: 98_123 },
+});
+```
+
+يُصدر أيضًا `run.progress.updated` بالحالة الطرفية.
+
+### قائمة {#list}
+
+```ts
+import { listRuns, getRun, deleteRun } from "@agent-native/core/progress";
+
+const active = await listRuns("steve@builder.io", { activeOnly: true });
+const run = await getRun("run-id", "steve@builder.io");
+await deleteRun("run-id", "steve@builder.io");
+```
+
+## HTTP API {#http}
+
+تم تركيبه على `/_agent-native/runs/*` بواسطة البرنامج الإضافي للمسارات الأساسية. **للقراءة فقط عبر HTTP** — تمر عمليات الكتابة عبر أدوات الوكيل نظرًا لأن الوكيل هو الكاتب الأساسي. جميع المسارات مخصصة للمالك.
+
+| الطريقة  | المسار                            |
+| -------- | --------------------------------- |
+| `GET`    | `/_agent-native/runs?active=true` |
+| `GET`    | `/_agent-native/runs/:id`         |
+| `DELETE` | `/_agent-native/runs/:id`         |
+
+```an-api title="List active runs" method="GET" path="/_agent-native/runs"
+{
+  "method": "GET",
+  "path": "/_agent-native/runs",
+  "summary": "List the caller's runs. The RunsTray polls this with active=true.",
+  "description": "Read-only and owner-scoped — every row has an `owner` column and every query filters on it, so callers only ever see their own runs. Writes (start/update/complete) go through the agent's `manage-progress` tool, not HTTP.",
+  "auth": "Session cookie (owner-scoped)",
+  "params": [
+    { "name": "active", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only `running` rows." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Array of AgentRun rows owned by the caller." }
+  ]
+}
+```
+
+## مكون UI {#ui}
+
+```tsx
+import { RunsTray } from "@agent-native/core/client/progress";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <RunsTray />
+    </header>
+  );
+}
+```
+
+أداة الرأس المضمّنة - قم بتثبيتها بجوار جرس الإشعارات. يظهر رمز القرص الدوار + شارة العد عندما تكون عمليات التشغيل نشطة؛ يؤدي النقر إلى فتح قائمة منسدلة تحتوي على شريط نسبة مئوية مباشر واحد لكل تشغيل. يخفي المشغل بالكامل في حالة عدم وجود عمليات تشغيل نشطة. استطلاعات الرأي `/_agent-native/runs?active=true` كل `pollMs` (افتراضي 3 ثوانٍ). يستخدم الرموز الدلالية shadcn، ويتكيف مع السمات الفاتحة والداكنة.
+
+## أداة الوكيل {#agent-tool}
+
+يتم تسجيل أداة `manage-progress` واحدة في كل قالب. تحدد المعلمة `action` العملية:
+
+| الإجراء    | الغرض                                                   |
+| ---------- | ------------------------------------------------------- |
+| `start`    | الاتصال بأعلى مهمة طويلة. تقوم بإرجاع معرف التشغيل.     |
+| `update`   | اتصل بشكل دوري أثناء المهمة بـ `percent` و/أو `step`.   |
+| `complete` | المحطة — إحدى `succeeded`، `failed`، `cancelled`.       |
+| `list`     | فحص عمليات التشغيل الأخيرة (التصفية حسب `active=true`). |
+
+### متى يبدأ الجري {#when-to-start}
+
+- استخدمه لأي شيء > ~5 ثوانٍ. الدوار الذي لا يحتوي على سياق يبدو متجمدًا.
+- يتم التحديث عند نقاط التفتيش الطبيعية، وليس في كل تكرار. كل 5-10% كثير.
+- **دائمًا** اتصل بـ `manage-progress` باستخدام `action=complete`، بما في ذلك مسارات الأخطاء. صف `running` اليتيم أسوأ من عدم وجود صف.
+- قم بالإقران مع `notify` عند الانتهاء حتى يرى المستخدم النتيجة عندما لا يشاهد الدرج بشكل نشط.
+
+## حافلة الأحداث {#event-bus}
+
+ينبعث حدثان على [event bus](/docs/automations#event-bus):
+
+| الحدث                  | الحمولة                            |
+| ---------------------- | ---------------------------------- |
+| `run.progress.started` | `{ runId, title, step? }`          |
+| `run.progress.updated` | `{ runId, percent, step, status }` |
+
+يمكن لـ [Automations](/docs/automations) الاشتراك في هذه — على سبيل المثال، _"إذا استغرق التشغيل وقتًا أطول من 5 دقائق، فأخبرني"_:
+
+```yaml
+---
+triggerType: event
+event: run.progress.updated
+condition: "status is failed"
+mode: agentic
+---
+Notify me that run {{runId}} has failed.
+```
+
+## كيفية العمل {#internals}
+
+- **نطاق المالك** — يحتوي كل صف على عمود `owner`؛ يتم تصفية كل استعلام عليه. يرى المستخدمون عمليات التشغيل الخاصة بهم فقط.
+- **تكامل الاستقصاء** — تستدعي كل طفرة `recordChange()`، لذا يتم إبطال صحة القوالب التي تستخدم [`useDbSync`](/docs/client) تلقائيًا دون أي أسلاك إضافية.
+- **اسم الجدول** — يحتوي إطار العمل أيضًا على جدول `agent_runs` لتتبع دورة حياة دورة حياة الوكيل الداخلي للدردشة. يستخدم التقدم البدائي `progress_runs` للفصل بين الاهتمامين.
+- **تثبيت النسبة المئوية** — يتم تثبيت القيم على `[0, 100]` وتقريبها إلى عدد صحيح عند الكتابة.
+
+## ما هي الخطوة التالية
+
+- [**Notifications**](/docs/notifications) — قم بالاقتران مع `manage-progress` (`action=complete`) لإخبار المستخدم عند انتهاء العمل
+- [**Automations**](/docs/automations) — يعمل جهاز المراقبة ببطء عبر `run.progress.updated`
+- [**Client**](/docs/client) — `useDbSync` لإبطال ذاكرة التخزين المؤقت في الوقت الفعلي

package/corpus/core/docs/content/locales/ar-SA/pure-agent-apps.md

@@ -0,0 +1,39 @@
+---
+title: "تطبيقات Pure-Agent"
+description: "التطبيقات التي يكون فيها الوكيل هو المنتج بالكامل: حلقة وكيل التطبيق هي الباب الأمامي، وتتم إضافة UI فقط عندما يحتاج إليه البشر."
+---
+
+# تطبيقات Pure-Agent
+
+تطبيق الوكيل النقي هو الحد الأدنى من تطبيق الوكيل الأصلي: حلقة وكيل التطبيق هي
+منتج، وليس لوحة معلومات. يمكنك إرسال طلب من المحطة، Slack، عبر البريد الإلكتروني،
+مهمة مجدولة، أو وكيل آخر، أو الدردشة — "تلخيص رسائل البريد الإلكتروني غير المقروءة"، أو "نشر
+المقاييس اليومية إلى Slack" - ويعمل الوكيل ويعيد النتيجة أينما كانت
+ينتمي. لا يزال تطبيقًا حقيقيًا: actions، الجلسات، حالة التطبيق، السجل،
+الإعدادات وبيانات الاعتماد وسجلات المشاركة كلها موجودة في SQL.
+
+```an-diagram title="The app-agent loop is the front door" summary="Many entry points reach one agent loop over SQL-backed actions and state; results return to wherever the request came from. UI is added only when humans need to supervise."
+{
+  "html": "<div class=\"diagram-pure\"><div class=\"diagram-col\"><div class=\"diagram-pill\">Terminal</div><div class=\"diagram-pill\">Slack · email</div><div class=\"diagram-pill\">Scheduled job</div><div class=\"diagram-pill\">Another agent (A2A)</div><div class=\"diagram-pill\">Chat</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\">App-agent loop</span><small class=\"diagram-muted\">actions · sessions · app state in SQL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Result returns<br><small class=\"diagram-muted\">to where it belongs</small></div></div>",
+  "css": ".diagram-pure{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-pure .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-pure .diagram-arrow{font-size:22px;line-height:1}.diagram-pure .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+قم بالوصول إلى هذا الشكل عند تشغيل العمل في الخلفية، ويترك الإخراج
+، فإن المجال عبارة عن طلقة واحدة، أو أنك تقوم بإنشاء نموذج أولي. لا يزال الوكيل بحاجة إلى UI —
+ليست لوحة تحكم، ولكنها مكان يمكن للبشر الإشراف عليه وتكوينه وتوجيهه —
+وهذا هو السبب وراء قيام تطبيقات الوكيل الخالص عادةً بتثبيت غلاف الدردشة المدمج.
+
+هذا هو شكل المنتج **بدون رأس**. دليل القرار الكامل، ما يأتي
+يتوفر الآن الصندوق والسقالة والوصول إلى الريبو وتشغيل المشاركة في مكان واحد:
+
+→ [**Agent Surfaces — Headless agent**](/docs/agent-surfaces#headless)
+
+## ما هي الخطوة التالية
+
+- [**Agent Surfaces — Headless**](/docs/agent-surfaces#headless) — دليل القرار الكامل بدون رأس وAPIs
+- [**Getting Started**](/docs/getting-started) — قم بإنشاء تطبيق دردشة أو وكيل بلا رأس أولاً
+- [**Dispatch**](/docs/template-dispatch) — قالب مساحة العمل الذي يمثل نقطة بداية رائعة للوكيل النقي
+- [**Messaging the agent**](/docs/messaging) — كيف يتحدث المستخدمون مع الوكيل عبر الويب، Slack، Telegram، البريد الإلكتروني
+- [**Recurring Jobs**](/docs/recurring-jobs) — المطالبات المجدولة التي يعمل الوكيل من تلقاء نفسه
+- [**Actions**](/docs/actions) — الأدوات التي سيتصل بها وكيلك النقي