# TaskOutput

يجلب المخرجات المتراكمة لمهمة خلفية قيد التشغيل أو مكتملة — أمر صدفة خلفي، أو وكيل محلي، أو جلسة بعيدة. استخدمه عندما تحتاج إلى فحص ما أنتجته مهمة طويلة الأمد حتى الآن.

## متى يُستخدم

- عندما تعمل جلسة بعيدة (مثل صندوق رمل سحابي) وتحتاج إلى stdout الخاص بها.
- عندما أُرسل وكيل محلي في الخلفية وتريد تقدماً جزئياً قبل عودته.
- عندما يعمل أمر صدفة خلفي منذ وقت كافٍ وتريد التحقق منه دون إيقافه.
- عندما تحتاج إلى تأكيد أن مهمة خلفية تحرز تقدماً فعلاً قبل الانتظار أطول أو استدعاء `TaskStop`.

لا تلجأ إلى `TaskOutput` تلقائياً. لمعظم العمل الخلفي يوجد مسار أكثر مباشرة — انظر الملاحظات أدناه.

## المعاملات

- `task_id` (سلسلة، مطلوب): معرف المهمة المُعاد عند بدء العمل الخلفي. ليس نفس `taskId` في قائمة المهام؛ هذا هو المقبض التشغيلي للتنفيذ المحدد.
- `block` (قيمة منطقية، اختياري): عندما تكون `true` (الافتراضي)، انتظر حتى تُنتج المهمة مخرجاً جديداً أو تنتهي قبل الإرجاع. عندما تكون `false`، أعد فوراً بكل ما تم تخزينه.
- `timeout` (رقم، اختياري): الحد الأقصى بالمللي ثانية للحجب قبل الإرجاع. ذو معنى فقط عندما يكون `block` هو `true`. الافتراضي `30000`، والأقصى `600000`.

## أمثلة

### مثال 1

اطلع على جلسة بعيدة دون حجب.

```
TaskOutput(task_id: "sess_01HXYZ...", block: false)
```

يُعيد أي stdout/stderr تم إنتاجه منذ بدء المهمة (أو منذ آخر استدعاء لـ `TaskOutput`، اعتماداً على وقت التشغيل).

### مثال 2

انتظر لفترة قصيرة حتى يُصدر وكيل محلي مزيداً من المخرجات.

```
TaskOutput(
  task_id: "agent_01ABCD...",
  block: true,
  timeout: 10000
)
```

## ملاحظات

- أوامر bash الخلفية: `TaskOutput` مُستغنًى عنه فعلياً لهذه الحالة. عند بدء مهمة صدفة خلفية، تتضمن النتيجة بالفعل مسار ملف مخرجاتها — اقرأ ذلك المسار مباشرة بأداة `Read`. تُتيح `Read` وصولاً عشوائياً وإزاحات أسطر ومنظوراً ثابتاً؛ لا تفعل `TaskOutput`.
- الوكلاء المحليون (أداة `Agent` المرسلة في الخلفية): عندما ينتهي الوكيل، تحتوي نتيجة أداة `Agent` بالفعل على ردّه النهائي. استخدمها مباشرةً. لا تقرأ ملف النصوص المُرمَّز — فهو يحتوي على تدفق استدعاءات الأدوات الكامل وسيفيض نافذة السياق.
- الجلسات البعيدة: `TaskOutput` هو الطريقة الصحيحة وأحياناً الوحيدة لتدفق المخرجات. فضِّل `block: true` بـ `timeout` معتدل على حلقات الاستقصاء المُحكمة.
- `task_id` غير معروف، أو مهمة جُمعت مخرجاتها بالقمامة، تُعيد خطأً. أعد إرسال العمل إذا كنت لا تزال بحاجة إليه.
- `TaskOutput` لا يوقف المهمة. استخدم `TaskStop` للإنهاء.
