run.start | agentName: string, agentId?: string | أول event في كل run. |
step.start | step: number | تبدأ step: استدعاء model واحد إضافةً إلى الـ tool calls التي يطلبها. يبدأ عدّ step من 1 (والـ run الذي يكمل من checkpoint يواصل العد). |
text.delta | text: string | جزء من نص الـ model، فور وصوله. |
object.delta | object: unknown | فقط لـ agent لديه output schema: الرد الذي حُلِّل حتى الآن، object جزئي قدر الإمكان (تُقطع قيمة الـ string غير المكتملة عند آخر نص وصل؛ ويُحذف الـ key أو الـ number غير المكتمل). يأتي بعد text.delta الذي يغيّره. لا يخضع لـ validation؛ والـ object المعتمد هو object الخاص بـ run.done. |
text.done | text: string | النص الكامل للـ step: تسلسل أحداث text.delta مجمّعة. فقط للـ steps التي تحتوي على نص. |
reasoning.start | (none) | يبدأ الـ model الـ reasoning في هذه الـ step. فقط مع خيار reasoning (أو model يُجري reasoning دائمًا). يتبعه reasoning.delta ثم reasoning.done، قبل أول text.delta أو tool.start في الـ step. |
reasoning.delta | text: string | جزء من نص الـ reasoning (أو من ملخصه). لا يدخل أبدًا في text.delta ولا في text الخاصة بـ run.done. |
reasoning.done | text: string, tokens?: number | انتهى الـ reasoning: يحتوي text على النص كله؛ وtokens موجودة إذا أبلغ الـ provider عن reasoning tokens حتى تلك اللحظة. وعندما يفشل استدعاء الـ model بعد reasoning فقط وتُعاد محاولته، ينتهي reasoning المحاولة الفاشلة هنا، قبل event الـ provider.retry؛ ويبدأ الـ reasoning في المحاولة الجديدة من جديد بـ reasoning.start. |
tool.start | toolCallId: string, toolName: string, args: Record<string, unknown>, executedBy?: 'provider', parentToolCallId?: string | يبدأ tool call. args هي arguments الـ model بعد تحليلها من JSON ({} إذا لم تكن JSON صالحًا). الـ call الذي يُجريه script في code mode يحمل parentToolCallId، وهو id استدعاء run_code (ويظهر أيضًا في tool.partial وtool.done وtool.error الخاصة به). والـ hosted tool الذي شغّله الـ provider داخل استدعاء الـ model يحمل executedBy: 'provider'؛ أي أنه لم يمر على أي permission rule ولا guardrail ولا approval ولا hook. يوجد واحد بالضبط لكل tool call حتى لو حدث pause: الـ call الذي توقف بانتظار approval (أو sign-in) ثم عمل يُبلغ عن tool.resume في الـ run المكمل، وليس tool.start آخر. |
tool.resume | toolCallId, toolName, args: Record<string, unknown> | يعمل الـ call المحسوم في استكمال بعد approval. صدر tool.start الخاص به من الـ run الذي توقف؛ عامله مثل tool.start عندما تتتبع الـ calls. |
tool.partial | toolCallId, toolName, output: unknown, index: number | snapshot من output أداة قيد التشغيل: الأداة التي تكون execute فيها async function* ترسل snapshot مع كل yield (راجع Streaming partial results). كل snapshot كاملة وتحل محل سابقتها؛ ويعدّ index الـ snapshots الخاصة بالـ call بدءًا من 0. آخر snapshot هي نفسها result في tool.done. وoutput مُرمَّزة بـ JSON مثل result. لا تصل الـ snapshots أبدًا إلى الـ model ولا إلى الـ transcript ولا إلى الـ checkpoints ولا إلى الـ traces. والـ snapshot الخاصة بـ sub-agent تحمل subagent. |
tool.done | toolCallId, toolName, result: unknown, durationMs: number, replacedByHook?: string, executedBy?: 'provider' | أرجع الـ tool call نتيجته. result هي القيمة كما تُرمَّز بـ JSON (undefined تصبح null، وDate تصبح string). ويُحسب durationMs من tool.start / tool.resume الخاص به. ويسمّي replacedByHook الـ hook الذي حلّت نتيجته { result } محل نتيجة الأداة (أو قامت مقامها). واستدعاء الـ hosted tool يحمل executedBy: 'provider' وresult فيه لا تتجاوز 20,000 حرف JSON. |
todo.updated | todos: Todo[], counts: { pending, in_progress, completed, total }, toolCallId: string | استدعاء todo_write ناجح من todo tools استبدل القائمة، مباشرة بعد tool.done للـ call نفسه. todos هي القائمة الجديدة كاملة ({ id, content, status })، وtoolCallId هو استدعاء todo_write. والنسخة الخاصة بـ sub-agent تحمل subagent. وتحتفظ UI bindings بالقائمة وتعرضها مباشرة (live). |
tool.error | toolCallId, toolName, error: { name: string, message: string }, durationMs: number, executedBy?: 'provider' | فشل tool call: رمى خطأً، أو لم تطابق الـ arguments الـ schema (name: 'ToolArgumentsValidationError')، أو أن الأداة غير موجودة أصلًا. واستدعاء الـ hosted tool الذي أبلغ الـ provider عن فشله يحمل executedBy: 'provider' وتكون error.name فيه 'HostedToolError'. يتلقى الـ model الخطأ بوصفه result للـ call ويكمل الـ run. |
approval.requested | approvalId: string, toolCallId, toolName, args: Record<string, unknown>, kind?: 'question' | 'sign-in', question?: { text, options?, allowFreeText? }, signIn?: { provider, displayName?, url } | يحتاج tool call إلى قرار من إنسان. يتوقف الـ run عندها؛ أكمله باستخدام agent.approvals.resolve() أو resumeAfterApproval() (راجع Approvals)، أو اعمل stream للاستكمال (راجع stream بعد approval). واستدعاء ask_question يحمل kind: 'question' وquestion الخاصة به؛ أجب عنها باستخدام agent.approvals.answer() (راجع سؤال المستخدم). والأداة التي تنتظر OAuth sign-in تحمل kind: 'sign-in' والرابط في signIn (راجع ما يراه المستخدم). |
permission.decision | toolCallId, toolName, decision: 'allow' | 'deny' | 'ask' | 'default', rule?: { index: number, reason?: string }, reason?: string, hook?: string, mode?: 'plan' | 'acceptEdits' | 'dontAsk', args?: Record<string, unknown>, at: string | كيف حسمت permission rules الـ tool call: بعد tool.start الخاص به، وقبل tool.done / tool.error / approval.requested للـ call نفسه. ويسمّي hook الـ preToolCall hook الذي رفض الـ call، وreason هو سبب الرفض (منه أو من needsApproval الخاصة بالأداة). لا يصدر إلا إذا ضبط الـ run قيمة permissions أو onPermissionDecision، أو كان فيه permission mode غير 'default' (ويكون mode موجودًا عندما يغيّر الـ mode النتيجة)؛ ويُحذف args مع redactContent. |
step.done | step: number, finishReason: string, usage?: { promptTokens, completionTokens, totalTokens, inputTokens, outputTokens, estimated: boolean, costUsd?: number } | انتهت الـ step. يأتي finishReason من الـ model ('stop'، 'tool_calls'، 'length'، …)، أو يكون 'awaiting-approval' أو 'aborted' أو 'steered' (أي أن run.steer() ألغى استدعاء الـ model، راجع Steering) أو 'error' عندما تنتهي الـ step بهذا الشكل (الـ run الذي يستنفد maxSteps بينما لا يزال الـ model يريد المتابعة ينتهي بـ run.done بالقيمة 'max-steps'). ويخص usage استدعاء الـ model لهذه الـ step، ويغيب إذا لم يُنتج الاستدعاء response؛ وpromptTokens/completionTokens أسماء بديلة (aliases) لـ inputTokens/outputTokens، وestimated تكون true عندما لا يُبلغ الـ provider عن أي شيء فتكون الأرقام تقديرية، وcostUsd يغيب إذا لم يُستخدم أي model سعره معروف، وcostPartial: true تشير إلى أن costUsd لا يشمل استدعاءً تسعيره مجهول. |
error | error: { name: string, message: string } | خطأ. إذا أنهى الـ run يتبعه run.done مع finishReason: 'error'. أما خطأ الـ provider الذي تُعاد محاولته تحت surfaceRetryableProviderErrors فتتبعه steps أخرى بدلًا من انتهاء الـ run. |
provider.retry | attempt: number, maxRetries: number, delayMs: number, error: { message: string, category?: string }, provider: string | فشل استدعاء model وتُعاد محاولته بعد delayMs (createAgent({ retry }) أو أي provider مع withRetry()). attempt هي المحاولة التي فشلت (1 = الأولى)؛ وcategory مثل 'rate-limit' أو 'timeout' … وتغيب إذا كانت مجهولة (خطأ 5xx مثلًا). |
provider.fallback | from: string, to: string, fromModel?: string, toModel?: string, error: { message: string } | لا يزال استدعاء الـ model يفشل بعد الـ retries، فيتولاه الـ provider التالي (createAgent({ fallbackModels }) أو أي provider مع withFallback()). from وto أسماء providers؛ وfromModel وtoModel هي ids الـ models، وبها تفرّق بين providerين لهما الاسم نفسه (مثلًا اثنان من models الـ OpenRouter). |
compaction.start | strategy: string, tokensBefore: number, contextWindow: number, thresholdTokens: number, trigger?: 'manual' | وجد الـ compaction hook (createAgent({ compaction })) أن طلب الـ model التالي يتجاوز الـ threshold فبدأ بضغطه. يتبعه compaction.done واحد بالضبط. وتشير trigger: 'manual' إلى استدعاء session.compact() (راجع context.cleared). راجع Context compaction. |
compaction.done | strategy: string, appliedStrategy?: string, tokensBefore: number, tokensAfter: number, prunedToolCallIds: string[], summary?: boolean, error?: { message: string }, unchanged?: true, trigger?: 'manual' | انتهى الـ compaction. تساوي tokensAfter قيمة tokensBefore وتكون unchanged هي true إذا لم يُضغط أي شيء (ولا تُصدر المحاولات اللاحقة التي لا تغيّر شيئًا على الـ transcript نفسه أي events)؛ وsummary موجودة إذا استُبدلت الـ turns القديمة بملخص؛ وerror موجودة إذا فشلت الـ strategy أو رجعت إلى fallback (ويكمل الـ run)؛ ويسمّي appliedStrategy الـ strategy التي طُبّقت نتيجتها عندما تختلف عن strategy ('prune-tool-results' بعد ملخص مرفوض). وتشير trigger: 'manual' إلى استدعاء session.compact(). |
heal.action | action: 'hint' | 'deny' | 'stop', toolName: string, reason: string, failure?: 'bad-input' | 'timeout' | 'missing-capability' | 'permission' | 'unknown' | تدخّل hook لإخراج run عالق من تعثّره (راجع createProgressGuard()). |
context.cleared | sessionId: string, messagesCleared: number | أفرغت session.clear() الـ transcript الخاص بـ session. يصل إلى مستمعي session.on()، لا إلى stream أي run. وcompaction.start / compaction.done الصادران من session.compact() يصلان إلى session.on() أيضًا ويحملان trigger: 'manual'. |
budget.exceeded | limit: string, value: number, max: number, scope: 'run' | 'session' | بلغت limits budget حدها: limit هو 'maxTokens' أو 'maxInputTokens' أو 'maxOutputTokens' أو 'maxCostUsd' أو 'maxDurationMs' أو 'maxSteps'، وvalue هو ما استُهلك، وmax هو الحد. يتبعه run.done ('budget-exceeded')؛ ومع onExceeded: 'throw' يأتي error ثم run.done ('error'). |
input.queued | id: string, text: string | قبلت run.enqueue() الـ input (id هو EnqueueResult.id، وtext نص المستخدم). قد يأتي في أي نقطة من الـ run، حتى داخل step. راجع Queued input. |
input.steered | id: string, text: string, mode: 'immediate' | 'queued' | قبلت run.steer() الـ input (id هو SteerResult.id). mode: 'immediate': أُلغي استدعاء الـ model الجاري بسببه، وتنتهي الـ step بـ step.done بالقيمة 'steered'؛ و'queued': ينتظر أقرب نقطة آمنة مثل enqueue(). راجع Steering. |
input.applied | id: string, step: number | انضم الـ input الذي كان queued (أو steered) إلى الـ transcript، مباشرة قبل استدعاء الـ model للـ step step: ويتبعه step.start للـ step نفسها. |
guardrail.tripped | name: string, kind: 'input' | 'output' | 'tool', reason: string, toolName?: string, info?: GuardrailTripInfo (ما أثار الـ guardrail: الأنواع والـ offsets، وليس النص المطابق أبدًا؛ راجع المجموعة الأساسية) | منع input أو output أو tool guardrail: قبل أول استدعاء model (input)، أو قبل text.done للـ step (output)، أو بعد tool.start للـ call (tool). يتبعه run.done ('guardrail')؛ ومع onTripped: 'throw' يأتي error ثم run.done ('error'). |
guardrail.rewrote | name, kind, reason, toolName?, info? | أعاد guardrail كتابة الـ input، أو نص الـ step (قبل text.done الذي يحمل النص الجديد)، أو arguments لـ tool call. ويكمل الـ run. |
agent.drift | model?: { from?: string, to?: string }, toolsAdded: string[], toolsRemoved: string[], toolsChanged: string[], instructions: boolean | run محفوظ في checkpoint أو متوقف بانتظار approval يكمله agent مختلف عن الذي حفظه، وقيمة onAgentDrift هي 'warn' (الافتراضي): يوضح الـ event ما الذي تغيّر. يصدر مباشرة بعد run.start للاستكمال، قبل أي event لـ step أو tool؛ ويكمل الـ run. ومع 'error' يُرفض الاستئناف بالخطأ LOUSHO_AGENT_DRIFT بدلًا من ذلك ولا يصدر هذا الـ event. راجع الاستئناف بـ agent تغيّر. |
handoff | from: string, to: string, toolCallId: string | سلّم الـ run المحادثة إلى agent آخر (Handoffs): بعد tool.start / tool.done لاستدعاء الـ handoff، وقبل أول step.start للهدف. وتخص steps الـ run من هذه النقطة الهدف؛ ويسمّي run.result.agentName الـ agent صاحب الرد النهائي. |
run.done | finishReason: string, text: string, usage?: { promptTokens, completionTokens, totalTokens, inputTokens, outputTokens, estimated: boolean, costUsd?: number, modelCalls?: number, hostedToolCalls?: { [tool: string]: number } }, object?: unknown | آخر event في كل run، مرة واحدة بالضبط، حتى لو أُلغي الـ run أو فشل أو توقف بانتظار approval. يطابق finishReason وtext قيمة run.result ('max-steps' عندما تُستنفد ميزانية maxSteps بينما لا يزال الـ model يريد المتابعة)؛ والـ run الفاشل له finishReason: 'error' وtext: '' وبلا usage. وusage للـ run كله: يعدّ modelCalls استدعاءات الـ model، ويعدّ hostedToolCalls استدعاءات الـ hosted tool التي شغّلها الـ provider لكل tool name (رسومها ليست ضمن costUsd). وobject هو الـ object المعتمد من run.result لـ agent لديه output schema (راجع Structured output)، ويغيب في غير ذلك. |