الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
مرّر store لـcreateAgent() ومرّر sessionId لـsend()، فيستمر الـ run رغم crash، أو restart، أو abort، أو approval (موافقة) من إنسان تستغرق أيامًا. ولا شيء هنا يعتمد على host معيّن: أي CheckpointStore — memoryStore()، أو SqliteStore، أو store الـ Cloudflare KV الذي يوفّره build cloudflare-worker، أو تنفيذك الخاص بثلاث دوال — وأي ApprovalStore تعمل بالطريقة نفسها. انظر أيضًا: إيقاف وإعادة تشغيل واستئناف، دليل قصير من البداية إلى النهاية.
خيار store هو الذي يتولّى التوصيل كله: store.checkpoints يحمل checkpoints الـ run، وstore.approvals يحمل توقفات الـ approval، وagent.approvals.resolve() تواصل كتابة checkpoints للـ run تحت sessionId الخاص به. stream() تأخذ sessionId أيضًا. وللـ sessions (الجلسات) checkpoints كذلك: agent.session({ id }) تحفظ checkpoint لكل turn، وagent.resume(id) (أو session.resume()) تُنهي session انقطعت — انظر durable sessions. تحت الغطاء، تشغّل createAgent() الدالة AgentExecutor.execute() مع sessionId وcheckpointStore. السلوك الموصوف أدناه هو سلوك الـ executor، والقسم المتقدم يعرض استدعاءاته.

ماذا يُحفَظ في الـ checkpoint، ومتى

الـ checkpoint هو كامل transcript الـ run، زائد عدد خطواته وusage وbusinessState وstatus. send() (وstream()) تكتبه تحت sessionId: الـ run الذي يفشل (خطأ من الـ provider، أو hook يرمي خطأ، أو PropagatingToolError، أو crash في الـ process) يحتفظ بآخر checkpoint بـ'in-progress'. وعندما يفشل برفض (وليس بـ crash)، يأخذ الـ checkpoint أيضًا الخطأ في lastError وعدد المحاولات الفاشلة في attempts، حتى تستطيع agent.pending() أن تميّز run يفشل مرة بعد مرة من run قطعه crash. وأول checkpoint يحفظه الـ run بعد ذلك (أي أنه تقدّم) يزيل الاثنين. أثناء عمل sub-agent، يُحفظ ما أنفقه حتى الآن على checkpoint الـ lead بعد كل استدعاء للـ model وكل نتيجة tool لديه (delegatedInFlight). أما الـ sub-agent نفسه فلا يُحفظ له checkpoint: إذا تعرّض الـ lead لـ crash في منتصف sub-agent ثم استؤنف، يعمل استدعاء task من جديد ويبدأ الـ sub-agent من الصفر، لكن استدعاءات الـ model في المحاولة المنقطعة تبقى محسوبة في usage الخاص بالـ run المستأنف (كـ run مفوَّض إضافي).

ماذا يحدث إذا أرسلت مرة ثانية بنفس sessionId

نتيجة استدعاء send() مرة أخرى بنفس sessionId (أو execute() في الـ executor) تعتمد على status المحفوظة:
  • run غير مكتمل ('in-progress': حدث crash، أو انقطع بـ abort، أو فشلت كتابة في الـ store). يُستأنف الـ run (agent.resume(sessionId) تفعل الشيء نفسه بدون input جديد). إذا كانت آخر turn للـ model فيها tool calls بلا نتيجة، فهي بالضبط ما يعمل أولًا، عبر مسار الـ tools العادي (validation للـ arguments، hooks، needsApproval، toolConcurrency)، بدون استدعاء الـ model مرة أخرى. بعد ذلك تكمل الحلقة بما تبقّى من ميزانية maxSteps، ويستمر usage من الإجماليات المحفوظة في الـ checkpoint (والأمر نفسه بعد agent.approvals.resolve()، من الـ snapshot).
    • يُضاف الـ input الجديد كرسالة user بعد نتائج الـ tools هذه. ولا يوضع أبدًا بين turn فيها tool calls ونتائجها، فيبقى الـ transcript صالحًا لكل provider. وهذا ما يسمح للـ user بأن يقاطع run (بـ abort) ويوجّهه برسالة جديدة.
    • الـ input الذي يعيد إرسال الرسالة نفسها التي بدأ منها الـ run — وهذا هو المعتاد عندما تريد retry للطلب نفسه بعد crash — يُعامَل كـ retry ولا يُضاف مرة أخرى. وinput: [] أيضًا يستأنف فقط.
  • run مكتمل ('finished'). تستمر الـ session كمحادثة: تبقى الرسائل المحفوظة، ويصبح input turn الـ user التالية. مرّر الرسائل الجديدة فقط؛ إذا أعدت إرسال السجل المحفوظ ثم رسائل جديدة، يُتعرَّف على السجل ولا يتكرر. steps وusage وtoolCalls في النتيجة تُعدّ من الصفر للـ run الجديد؛ وmessages هي المحادثة كلها.
  • متوقف على approval ('awaiting-approval'). ترمي send() الخطأ SessionAwaitingApprovalError (وفيه sessionId وapprovalId) ولا تستدعي الـ model ولا أي tool: لا يجوز لـ input جديد أن يتخطى قرارًا معلّقًا. احسمه أولًا بـagent.approvals.resolve()، ثم أرسل الرسالة الجديدة.
تُتجاهل رسائل الـ system في input عندما يُضاف input إلى session محفوظة (لديها الـ system prompt الخاص بها أصلًا). إذا أردت إنهاء session والبدء من جديد بنفس الـ id، استدعِ store.checkpoints.delete(sessionId).

approval في منتصف batch من tool calls

عندما تطلب turn واحدة للـ model عدة tools وبعضها يحتاج approval، تعمل الـ calls التي لا تحتاج approval وتُسجَّل، ويتوقف الـ run مرة واحدة على كل call تحتاج approval (approvalIds، وسجل approval واحد لكل منها؛ انظر عدة calls في خطوة واحدة). الـ calls التي منعها steer من البدء، وcalls الـ handoff في الـ turn، تُسجَّل في الـ approval snapshot (remainingToolCalls). وبمجرد حسم آخر call متوقفة، تقوم agent.approvals.resolve() — ومن تحتها الدالة المصدّرة resumeAfterApproval() — بما يلي:
  1. تسجّل نتيجة كل call متوقفة، بترتيب الاستدعاء: نتيجة الـ tool إذا وُوفق عليها، أو نتيجة رفض منظمة { error, note } إذا رُفضت؛
  2. تشغّل الـ calls المتبقية بمنطق الـ batch نفسه: قد تعمل، أو تفشل في الـ validation، أو توقف الـ run مرة أخرى على approval أخرى (approvalId جديد؛ احسمه بالطريقة نفسها، وكرّر حسب الحاجة)؛
  3. تستدعي الـ model بمجرد أن يصبح لكل call في الـ turn نتيجة واحدة بالضبط.
يستخدم الـ run المستأنف approvalStore نفسه لأي approval لاحقة، إلا إذا مرّرت واحدًا آخر في الخيارات.

الاستعادة بعد crash

الـ run الذي انقطع (تعرّضت الـ process لـ crash أو قُتلت في منتصف turn)، أو المتوقف على approval، يبقى في store.checkpoints إلى أن يكمله أحد. تعرض agent.pending() هذه الـ runs عبر كل session وكل id من send(msg, { sessionId })، فتستطيع الـ process التي أُعيد تشغيلها أن تجدها:
تُرجع agent.resume() الـ ExecutionResult المكتمل (أو null إذا لم يكن هناك شيء معلّق)؛ ولا تُرجع stream. إذا أردت متابعة أحداث run مستأنف، فأنشئ له stream بدلًا منها: agent.stream([], { sessionId }) تستأنف checkpoint غير مكتمل من نوع kind: 'run' بدون input جديد (انظر أعلاه) وتُرجع الـ AgentRun المعتاد. أما الـ run المتوقف فيُبث بـagent.approvals.streamResolve(). تقرأ pending() من الـ checkpoint store المشترك، فتعرض أيضًا runs تعمل الآن في process أخرى أو replica أخرى (كـ'in-progress'، بدون lastError)، وليس فقط تلك التي تعرّضت لـ crash. انظر أدناه لماذا يكون استئناف أيٍّ منها آمنًا. كل مدخل شكله { sessionId, kind, checkpointId, status, approvalId?, approvalKind?, step, lastError?, attempts? }:
  • sessionId هو ما تأخذه agent.resume(): id الـ agent.session() لـ turn في session (kind: 'session'، والـ checkpoint الخاص بها <id>.turn-<n>)، أو id الـ send(msg, { sessionId }) (kind: 'run'، ويشمل الـ forks).
  • status تكون 'in-progress' (انقطع) أو 'awaiting-approval' (احسم approvalId بـagent.approvals.resolve()؛ وagent.approvals.list() تعرض الـ call).
  • يُعيَّن lastError عندما تفشل آخر محاولة لـ turn في session، أو لـ run من send(msg, { sessionId }) (kind: 'run')؛ ويعدّ attempts المحاولات الفاشلة المتتالية. مع retryable: false (مثلًا 400 من الـ provider) سيفشل مرة أخرى: أصلح السبب قبل agent.resume()، أو تخلّص منه بـagent.session({ id }).discardPending() (للـ run: store.checkpoints.delete(id)). ومدخل 'in-progress' بدون lastError يعني أنه انقطع (crash)، أو أنه ما زال يعمل.
والـ run الذي ما زال يعمل في أي process يظهر هو أيضًا كـ'in-progress'. واستئنافه آمن: الـ run يمسك lease (انظر Run leases)، فتفشل agent.resume() بـLOUSHO_SESSION_BUSY قبل أن يعمل أي شيء، بدلًا من تشغيل الـ tool calls الخاصة به مرة أخرى. الـ checkpoint الذي لا يمكن قراءته (كتابة انقطعت بسبب انقطاع الكهرباء على store لا يملك كتابات durable) يظهر كـ'in-progress' مع lastError.code بقيمة LOUSHO_CHECKPOINT_CORRUPT (retryable: false)، وهو الخطأ نفسه الذي تفشل به send() وresume()؛ تخلّص منه بـdiscardPending() (أو clear())، أو بـstore.checkpoints.delete(id) إذا كان run.

الاستعادة التلقائية

تطبّق agent.recover() هذه الوصفة نيابةً عنك، في الخلفية: كل intervalMs (الافتراضي 30 ثانية) تجلب قائمة agent.pending() وتستدعي agent.resume() على كل run بـ'in-progress'. شغّلها مرة واحدة لكل process، بجانب الكود الذي يخدم الـ traffic:
ما يفعله كل sweep مع كل run معلّق:
  • 'in-progress': يستأنفه من آخر checkpoint له، فلا تُعاد الخطوات المكتملة أبدًا (الـ tool التي كانت في منتصف call تعمل من جديد: اجعلها idempotent).
  • 'awaiting-approval' (approval لـ tool أو ask_question): يتركه؛ يحسمه الإنسان بـagent.approvals.resolve().
  • run يحتوي lastError الخاص به على retryable: false: يتركه، لأنه سيفشل بالطريقة نفسها؛ وتظل agent.pending() تعرضه.
  • run فشل مؤخرًا: يتخطّاه حتى ينقضي الـ backoff الخاص به، ويتضاعف intervalMs مع كل محاولة فاشلة متتالية، حتى 15 دقيقة.
  • run فشل maxAttempts مرة متتالية (الافتراضي 10): يُعزل (quarantine). تتوقف الحلقة عن استئنافه وتستدعي onQuarantined(run) مرة واحدة. وتظل agent.pending() تعرضه، وتظل agent.resume() تشغّله. حفظ أي تقدّم يصفّر العدّاد. والفشل الذي يقتل الـ process لا يسجّل محاولة، فلا يُحتسب. ومع retryWithDiagnosis: true، يحصل الـ run (وليس turn في session) أولًا على محاولة أخيرة: fork اسمه <id>.heal، يُستأنف من الخطوة نفسها، مع ملاحظة توضّح سبب فشله. إذا اكتمل الـ fork، يُحذف الأصلي ويبلّغ onRecovered بـ id الأصلي. وإذا وصل هو أيضًا إلى الحد، يُعزل الاثنان. تقتبس الملاحظة الخطأ كبيانات وتحدّ من طوله، لأن الخطأ قد يحمل مخرجات tool. ويجب أن يحتفظ الـ store بـ history.
  • أثناء انقطاع الـ provider: بعد 3 أخطاء provider متتالية، على أي runs، تتوقف الحلقة مؤقتًا وتستدعي onOutage(true). بعد ذلك تجرّب run واحدًا في كل مرة، على فترات تطول حتى 15 دقيقة، وبمجرد أن يمر أحدها عبر الـ provider تعود إلى العمل العادي وتستدعي onOutage(false). ولا يُعزل أي شيء بسبب أخطاء الـ provider خلال التوقف، فلا يستهلك الانقطاع محاولات الـ runs السليمة. ومفتاح API الخاطئ لا يُحتسب انقطاعًا، لأن الانتظار لا يصلحه.
  • run ما زال يعمل في process أخرى، أو run لم تنتهِ بعد صلاحية الـ run lease الخاص بالـ process التي تعرّضت لـ crash: يُرفض استئنافه بـLOUSHO_SESSION_BUSY قبل أن يعمل أي شيء، بصمت، ويحاول sweep لاحق مرة أخرى بمجرد تحرّر الـ lease. لذلك يكتمل الـ run الذي تعرّض لـ crash خلال انتهاء lease واحد زائد intervalMs واحد بعد الـ crash على الأكثر، ويمكن لكل replica أن تشغّل recover(): تضمن الـ leases أن واحدة فقط منها تستأنف الـ run. كما أن الحلقة لا تبدأ أبدًا استئنافًا ثانيًا لـ run تستأنفه بالفعل.
يُبلَّغ onError(error, run?) عن sweep لم يتمكن من قراءة قائمة الـ store (run بقيمة undefined) وعن استئناف فشل (run معيّن)؛ وتستمر الحلقة في الحالتين. ويتلقى onRecovered(run, result) كل run أكملته. إلغاء signal (أو stop()) يوقف الـ polling ويُجري abort للاستئنافات الجارية (تبقى الـ checkpoints الخاصة بها للتشغيل التالي)؛ وتكتمل done بمجرد أن يستقر كل شيء. تُبقي الحلقة الـ process حيّة إلى أن توقفها. ومثل pending()، ترمي recover() الخطأ LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE إذا لم يوجد checkpoint store. ومع store مخصص لا يملك leases (acquireLease)، لا شيء يمنعها من استئناف run ما زال يعمل في process أخرى: شغّلها في process واحدة فقط. للحصول على نظرة عامة على الاستعادة إلى جانب الـ progress guard وimproveAgent()، انظر التعافي الذاتي والتحسين الذاتي.

Run leases

أثناء عمل run لديه checkpoints (turn في session، أو run من send(msg, { sessionId })، أو استئناف بعد approval)، يمسك lease على id الـ checkpoint الخاص به في الـ checkpoint store: owner id وانتهاء صلاحية بعد 30 ثانية، يتجدد كل 10 ثوانٍ. أي process أخرى أو replica أخرى أو store object آخر يحاول تشغيل الـ id نفسه أو استئنافه خلال هذا الوقت — send() التي كانت ستستأنف الـ turn المعلّقة أولًا، أو agent.resume()، أو agent.approvals.resolve() — يفشل بـLOUSHO_SESSION_BUSY قبل أن تعمل أي tool أو يُستدعى أي model (وتبقى الـ approval المحسومة معلّقة). لذلك لا تشغّل replicaان خلف load balancer أبدًا tool calls الـ turn نفسها مرتين. يصح هذا للـ replicas على host واحد تتشارك ملف SQLite واحدًا على قرص محلي، أو لـ store تنفّذه بنفسك على database مشتركة؛ أما SQLite على filesystem شبكي أو عبر أكثر من host فغير مدعوم. انظر مشاركة ملف SQLite. يُستولى على الـ lease الذي مات ماسكه بمجرد انتهاء صلاحيته. يُحكم على انتهاء الصلاحية بساعة الـ process التي تريد الـ lease مقابل وقت الانتهاء الذي كتبه الماسك بساعته هو، لذلك ينتظر الـ file store وSQLite store فترة lease إضافية (30 ثانية) بعده: الـ run الذي تركته process تعرّضت لـ crash على جهاز آخر يُستولى عليه بعد 30 إلى 60 ثانية من آخر heartbeat له، والـ replicas التي تختلف ساعاتها بأقل من 50 ثانية تقريبًا لا تستولي أبدًا على الـ runs الحية الخاصة ببعضها. أبقِ ساعات الـ replicas متزامنة (NTP)؛ فالفرق الأكبر قد يجعل replicaين تشغّلان الـ turn نفسها. يستولي الـ file store وSQLite store على الـ lease فورًا، بدون انتظار، فقط عندما يثبت أن ماسكه قد انتهى:
  • run من الـ process نفسها (الـ thread نفسه ونسخة الـ SDK نفسها) لم يعد يعمل، فلا ينتظر مسار «أعد التشغيل واستأنف» المعتاد؛
  • على Linux، process خرجت، على الـ host نفسه والـ boot نفسه والـ PID namespace نفسه (يسجّل الـ lease الـ boot id والـ PID namespace ووقت بدء الـ process، فلا يُحتسب process id أُعيد استخدامه حيًّا أو ميتًا عن طريق الخطأ)؛
  • على macOS وWindows، process id على الـ host نفسه لم يعد موجودًا.
أما run من worker thread آخر في الـ process نفسها، أو من container آخر بالـ hostname نفسه على volume مشترك (أو process أُعيد تشغيلها في container جديد)، فلا يُستولى عليه مبكرًا أبدًا: ينتظر انتهاء الصلاحية. owner id الخاص بـ lease الـ run هو fencing token. يجدد الـ heartbeat الـ lease فقط طالما أن الـ run يمسكه (ولا يسترجع أبدًا lease أخذته process أخرى، ولا lease تحرّر بعد أن أكملت process أخرى الـ run)، وكل checkpoint يحفظه الـ run يُكتب فقط إذا كان الـ run ما زال يمسك الـ lease، بشكل atomic مع هذا الفحص في الـ file store وSQLite store والـ in-memory store. فإذا علّق run مدة أطول من الـ lease الخاص به (توقفت الـ process مؤقتًا، أو انحجز الـ event loop) وأخذته process أخرى، يتوقف الـ run المعلّق بـLOUSHO_SESSION_BUSY عند الـ checkpoint التالي بدلًا من الكتابة فوق تقدّم الماسك الجديد، ولا تُضاف النتيجة المتأخرة لـ turn في session إلى الـ transcript. أما tool call كان الـ run المعلّق ينفّذها عندما خسر الـ lease فلا تُلغى: اجعل الـ tools idempotent في أي مكان قد يحدث فيه تعليق. يستولي الـ file store وSQLite store والـ in-memory store على الـ leases بشكل atomic. لا يملك KV عملية compare-and-swap: يكتب KVStore الـ lease، وينتظر 50 ms ثم يقرأه من جديد، وهذا يرتّب الطلبات في موقع واحد لكن ليس عبر edge locations ضمن تأخير الانتشار الخاص بـ KV؛ والـ saves المحمية (fenced) فيه قراءة ثم كتابة. يشارك الـ CheckpointStore المخصص إذا نفّذ acquireLease(id, owner, ttlMs) (عملية atomic: «خذ أو جدّد إلا إذا كان owner آخر يمسك lease لم تنتهِ صلاحيته»، تُرجع true عند الاستيلاء) وreleaseLease(id, owner)؛ وبدونهما تعمل الـ runs بدون leases. ويمكنه أن يضيف renewLease(id, owner, ttlMs) (يجدد فقط الـ lease الخاص بالـ owner نفسه) وsaveIfLeased(id, checkpoint, owner) (يحفظ فقط طالما أن الـ owner يمسك الـ lease، بشكل atomic)؛ وبدونهما يجدد الـ run الـ lease الخاص به بـacquireLease مباشرة قبل كل save، وهذا يترك نافذة قصيرة. أثناء rolling upgrade من إصدار لا يحتوي على run leases، لا تأخذ الـ replicas القديمة leases ولا تحترمها، فقد تظل الـ turn تعمل على replica قديمة وأخرى جديدة في الوقت نفسه إلى أن تشغّل كل الـ replicas الإصدار الجديد. وملف SQLite database الذي يُفتح بهذا الإصدار يُجرى له migration (جدول leases) وبعدها ترفضه الإصدارات الأقدم؛ للرجوع، استرجع نسخة من الملف. تستخدم الـ schedules الآلية نفسها: fireSchedule() (وبالتالي startSchedules()) تحجز وقت الإطلاق لكل schedule في الـ checkpoint store الخاص بالـ agent أولًا، فتشغّل الـ replicas التي تطلق الـ tick نفسه مرة واحدة فقط. تحتاج agent.pending() إلى checkpoint store فيه list(): الـ file store وSQLite store والـ in-memory store وKV store كلها تملكها (KVStore يعرض القائمة فقط إذا كان الـ namespace binding الخاص به يحتوي list، مثل الحقيقي). على CheckpointStore مخصص، تُرجع list({ status? }) القيم { sessionId, status, checkpoint } لأحدث checkpoint لكل id؛ وlistCheckpoints(entries, options) تتولى الفلترة والترتيب نيابةً عنك. وبدونها ترمي agent.pending() الخطأ LOUSHO_CONFIG_INVALID؛ وبدون checkpoint store أصلًا، ترمي LOUSHO_CONFIG_MISSING_CHECKPOINT_STORE.

الضمانات

  • كل tool call تأخذ نتيجة واحدة بالضبط، بترتيب الاستدعاء، مهما تتابعت الـ crashes والـ aborts والتوقفات والاستئنافات. (الـ call التي انقطعت بـ abort تأخذ نتيجة “cancelled”؛ والـ call المرفوضة تأخذ نتيجة رفض.)
  • لا يُعاد تنفيذ أي call لها نتيجة مسجلة أبدًا. تُحفظ كل نتيجة في الـ checkpoint بالـ toolCallId الخاص بها بمجرد انتهاء الـ call — حتى لو انتهت بعد call أبطأ قبلها في الـ turn نفسها — فيشغّل الـ run المستأنف فقط الـ calls التي ليست لها نتيجة مسجلة.
  • لا يُولَّد turn الـ model المحفوظ في checkpoint من جديد أبدًا. إذا ماتت الـ process بعد أن ردّ الـ model، ينفّذ الـ run المستأنف الـ tool calls الموجودة في الرد بدلًا من سؤال الـ model مرة أخرى (فلا تكلفة إضافية ولا خطة مختلفة).
  • يستقبل الـ provider دائمًا transcript صالحًا: تأتي نتائج الـ tools مباشرة بعد turn الـ tool calls الخاصة بها، وتأتي رسائل الـ user الجديدة بعدها.
  • تعمل الـ call الموافق عليها مرة واحدة على الأكثر. حسم الـ approval يحتفظ بـ checkpoint الـ run المتوقف: يُحفظ من جديد كـ'in-progress' مع تعليم الـ call الموافق عليها بأنها بدأت (startedToolCallIds) قبل أن تعمل، ويُحفظ مرة أخرى مع نتيجتها قبل أن يكمل الـ run. إذا ماتت الـ process والـ call الموافق عليها قيد التشغيل، فلا تضيع الـ turn: تعرضها pending()، واستئنافها لا يشغّل الـ call مرة أخرى. تأخذ الـ call نتيجة خطأ (kind: 'interrupted') تخبر الـ model بأنها ربما أحدثت أثرًا وربما لا، فيستطيع الـ model أن يتحقق أو يسأل بدلًا من تكرارها بصمت — فقد وافق الإنسان عليها مرة، لا مرتين.
  • لا تعود الـ approval القديمة أبدًا. تُكمل الـ approval الـ run الخاص بها فقط طالما أن checkpoint هذا الـ run ما زال ينتظرها. إذا حُذف الـ checkpoint (checkpoints.delete(id)، أو discardPending()، أو prune) أو استُبدل بـ run أحدث تحت الـ id نفسه، يفشل حسمها بـLOUSHO_APPROVAL_ORPHANED ويسحبها، بدون تشغيل الـ tool أو المساس بالـ run الأحدث. وتسحب discardPending() فورًا approvals الـ turn التي تخلّصت منها.

تشغيل job مرة وحدة (إعادة تسليم الـ webhook)

يسلّم الـ webhook أو الـ queue مرة واحدة على الأقل، فقد يصل الـ payload نفسه مرتين. وإرساله مرة أخرى بنفس sessionId ليس no-op: بمجرد أن يصبح الـ run الأول 'finished'، تصبح send() الثانية turn جديدة في المحادثة وتستدعي الـ model من جديد (في اختبار لدى أحد المستخدمين، أعادت تشغيل سبعة استدعاءات للـ model). إذا أردت تشغيل الـ job مرة واحدة، فاشتق الـ sessionId من id التسليم وافحص الـ checkpoint قبل الإرسال:
الفحص ثم الإرسال ليس atomic: قد لا يجد تسليمان متزامنان أي checkpoint. رتّب التسليمات لكل id بالتتابع (queue مفتاحها deliveryId، أو unique-insert في الـ database الخاصة بك) وأبقِ الـ run lease مفعّلًا (انظر Run leases) حتى تفشل الـ process الثانية بـLOUSHO_SESSION_BUSY بدلًا من تشغيل الـ job مرتين. ويجب أن تظل الـ tools التي تعمل من جديد عند الاستئناف idempotent، لذلك مرّر أيضًا toolCallId الخاص بالـ call كـ idempotency key لكل side effect (انظر القسم التالي).

At-least-once tools: اجعل الـ side effects idempotent

الـ tool التي كانت قيد التشغيل عندما ماتت الـ process ليست لها نتيجة مسجلة، فتعمل من جديد عند الاستئناف. أي أن تنفيذ الـ tools هو at-least-once، وليس exactly-once. أما الـ tools التي لها side effects (سحب مبلغ من بطاقة، إرسال بريد إلكتروني): فإما أن تضعها خلف needsApproval وإما أن تجعلها idempotent. يُمرَّر toolCallId الخاص بكل call — وهو id الـ model للـ call، ولا يتغير عندما تُعاد الـ call نفسها في الاستئناف — إلى execute، فيعمل كـ idempotency key ضد إعادة تشغيل call واحدة:
(يُعيَّن toolCallId في كل run لـ tool، بما في ذلك الـ tools التي تمر عبر sandboxExecute.) الـ file tools المدمجة آمنة لإعادة التشغيل. write_file تكتب المحتوى نفسه مرة أخرى؛ وedit_file التي يكون تعديلها موجودًا أصلًا في الملف (اختفى old_string، ويوجد new_string غير الفارغ) تنجح وتذكر أن التعديل مطبّق أصلًا، بدلًا من أن تخبر الـ model بأن تعديلًا مطبّقًا قد فشل. ومع WorkspaceCheckpoints، يُحفظ الـ backup الخاص بكل تغيير قبل كتابة الملف، وتحتفظ إعادة التشغيل بأول backup، فيُرجع rewind() المحتوى الأصلي حتى بعد crash (انظر Workspace tools). أما tool الـ shell فليست آمنة: الأمر الذي كان قيد التشغيل عندما ماتت الـ process يعمل من جديد. يحدد toolCallId (وctx.approval.id للـ call الموافق عليها) call واحدة أنشأها الـ model، ويحمي فقط من تشغيل هذه الـ call مرتين. إذا ماتت الـ process قبل تسجيل الـ call، قد ينشئ الـ model الـ call نفسها من جديد كـ call جديدة بـ id جديد وapproval جديدة، فلا يعود الـ id مطابقًا. والـ side effect الذي يجب أن يحدث مرة واحدة لكل حدث business (claim واحد، فاتورة واحدة) يحتاج idempotency key من بياناتك أنت، مثل id الـ claim في الـ arguments، تفحصه أو تمرّره إلى النظام الذي تكتب فيه:

Checkpoint history

يُكتب فوق سجل الـ checkpoint مع كل save، فتضيع خطوات الـ run الأقدم بمجرد أن يتقدم. ويمكن للـ store أيضًا أن يحتفظ بـ history محدود لكل session: كل save() يضيف السجل إلى ring (أحدث historyLimit حفظة، والافتراضي 50؛ ويُحذف الأقدم). وعلى هذا يُبنى replay لـ run أو عمل fork له من خطوة أقدم. الـ stores التي تحتفظ بـ history: مثال، مع store الذاكرة:
  • تُرجع history(sessionId, { limit? }) مدخلات { step, savedAt, status, checkpoint }، الأحدث أولًا (step هو checkpoint.stepIndex، وsavedAt timestamp بصيغة ISO، وstatus تكون 'in-progress' لـ checkpoint بلا حالة). يحفظ الـ executor بعد كل turn للـ model وكل batch من الـ tools، فلكل session مدخل لكل save. تحتوي المدخلات على checkpoints كاملة، لذا خفّض historyLimit للـ transcripts الطويلة. الـ session غير المعروفة تُرجع [].
  • history اختيارية في CheckpointStore: الـ store المخصص الذي لا يملكها يستمر في العمل، وتُرجع له getCheckpointHistory() القيمة undefined بدلًا من أن ترمي خطأ.
  • يحتفظ KVCheckpointStore بمفتاح index واحد لكل session (<prefix><sessionId>#history، وفيه ids المدخلات من الأقدم إلى الأحدث) وبمفتاح واحد لكل مدخل (<prefix><sessionId>#history/<id>)، فلا توجد قيمة تكبر مع الـ history. يبقى أحدث checkpoint عند <prefix><sessionId>، فيُقرأ الـ store المكتوب قبل وجود الـ history بشكل عادي. يكتب الـ save الـ checkpoint، ثم المدخل، ثم الـ index، ثم يحذف المدخلات التي أسقطها: الـ crash بين كتابتين يترك في أسوأ الأحوال مدخلًا غير مدرج في الـ index (تنتهي صلاحيته مع الـ TTL)، ولا يترك أبدًا store غير قابل للقراءة. لا يملك KV transactions، فقد يضيّع حفظان متزامنان للـ session نفسها تحديثًا واحدًا للـ index (يغيب المدخل عن history())، وقد يغيب مدخل لفترة في edge location أخرى (eventual consistency؛ وتتخطاه history()). وجّه طلبات الـ session إلى موقع واحد عندما يكون ذلك مهمًا. يكلّف كل save عملية get واحدة وعمليتي put إضافيتين؛ وhistoryLimit: 0 يعطّلها.
  • يكتب الـ file store الخاص بـ Agent Forge الـ history في ملف واحد لكل session (.lousho/agents/<id>/checkpoint-history/<session>.json، والاستبدال atomic). الملف الذي تلف بسبب crash يُقرأ كأنه بلا history، ويبنيه الـ save التالي من جديد.
  • يحتفظ SqliteStore بالـ history في جدول جديد checkpoint_history يُضاف عند فتح ملف database موجود. وتزيل prune() مدخلات الـ history الأقدم من الـ cutoff الخاص بها.

Fork و replay

تبدأ agent.fork(sessionId, { fromStep, patch? }) session جديدة من خطوة في history لـ session أخرى: «ماذا لو أعادت الـ tool شيئًا آخر في الخطوة 1؟». تأخذ أحدث مدخل في الـ history للخطوة fromStep، وتطبّق patch، وتحفظ الناتج كـ checkpoint بـ'in-progress' للـ session الجديدة على store.checkpoints، وتُرجع { sessionId, step, checkpoint }. استأنف الـ fork مثل أي run غير مكتمل بـagent.resume(fork.sessionId):
AgentExecutor.fork() هي العملية نفسها على الـ executor؛ انظر القسم المتقدم. تُجري agent.fork() عملية fork لـ run واحد من الـ checkpoint history الخاص به. إذا أردت تفريع محادثة agent.session() متعددة الـ turns، فاستخدم session.history() وsession.fork({ fromStep })، وكلاهما يعمل من الـ transcript المحفوظ للـ session مع أي store (الـ turns المنتهية لا تحتفظ بـ checkpoint history)؛ انظر عمل fork للـ session.
  • يُطبَّق patch بهذا الترتيب: messages(messages) يعيد كتابة الـ transcript؛ businessState يستبدل القيمة المحفوظة؛ toolResult: { toolCallId, result } يستبدل نتيجة تلك الـ call في مكانها — الموضع نفسه والـ call id نفسه واسم الـ tool نفسه، فيبقى الـ transcript صالحًا لكل provider — أو يسجلها إذا لم تكن للـ call نتيجة بعد؛ appendInput يضع رسالة user في الانتظار، تُرسل بعد أي tool calls ما زالت معلقة.
  • يحتفظ الـ fork بعدد خطوات الـ checkpoint المصدر وusage الخاص به، فينطبق عليه ما تبقّى من ميزانية maxSteps. لا تُعاد نتائج الـ tools المسجلة؛ وتعمل الـ tool calls التي بلا نتيجة أولًا، مثل أي استئناف (أي أن fork لمدخل 'awaiting-approval' يمر على needsApproval من جديد؛ ولا ينتقل approvalId القديم).
  • يسمّي newSessionId الـ fork؛ الافتراضي <sessionId>.fork-<n>، وn هو أول رقم ليس له checkpoint. يُرفض newSessionId الذي له checkpoint أصلًا.
  • الخطوة غير الموجودة في الـ history — الـ session غير معروفة، أو الخطوة لم تعمل أبدًا، أو حُذفت بعد تجاوز historyLimit — ترمي SDKError بكود LOUSHO_CHECKPOINT_NOT_FOUND، وتعدّد رسالته الخطوات المحفوظة. والـ store الذي لا يملك history() لا يستطيع إجراء fork (ConfigurationError).
  • تأخذ compareTrajectories(a, b) checkpointين أو transcriptين وتُرجع خطوات كل run — خطوة لكل turn للـ assistant: نصها وtool calls الخاصة بها مع نتائجها — وdivergedAt (أول خطوة تختلف، بغض النظر عن ids الـ tool calls)، وdrift، وهو فروق ترتيب الـ tools والـ arguments وعدد الخطوات وسبب الإنهاء، بالشكل نفسه الذي يستخدمه lousho eval --drift.

استئناف run بعد تغيّر الـ agent

يحمل كل checkpoint وكل approval snapshot fingerprint للـ agent (بصمة): id الـ model، واسم كل tool مع hash للـ JSON input schema الخاص بمدخلها، وhash لتعليمات النظام — زائد SHA-256 قصير على كل الأجزاء، محسوب بـ Web Crypto. الدوال والقيم التي لا تُسلسَل (execute الخاصة بالـ tool، الـ hooks، الـ callbacks) ليست جزءًا منها، فتعديل الكود وحده لا يُحتسب تغييرًا أبدًا. تُحفظ الأجزاء كلٌّ على حدة، حتى يستطيع الـ mismatch أن يذكر بالضبط ما الذي تغيّر. عندما يُستأنف run — agent.resume(id)، أو session.resume()، أو execute() لاحقة على sessionId غير مكتمل، أو agent.approvals.resolve() والنسخ الـ streamed — تُقارَن fingerprint الـ agent الذي يستأنف بالمحفوظة، قبل أي استدعاء للـ model أو تشغيل لـ tool. ويقرر onAgentDrift على createAgent() (وعلى AgentExecutor.execute() / الدالة المصدّرة resumeAfterApproval()) ما يفعله الاختلاف: الـ tool call المعلّقة التي لم تعد الـ tool الخاصة بها موجودة — استدعتها آخر turn للـ model وليست لها نتيجة بعد، أو وافق عليها الإنسان — تُرفض دائمًا بـLOUSHO_RESUME_TOOL_MISSING، مهما كان الخيار.
ملاحظات:
  • الـ checkpoints والـ snapshots المكتوبة قبل وجود هذه الميزة لا تملك fingerprint، وتُستأنف تمامًا كما في السابق، بدون تحذير.
  • يحفظ run الخاص بـdynamic agent الـ ctx والـ model الذي اختاره في الـ checkpoint (runConfig)، ويستخدمهما الاستئناف بعد crash: الـ model المحفوظ، وtools وتعليمات تُحسب من جديد بالـctx المحفوظ (سابقًا كان الحساب يتم بـinput: [] وبدون metadata).
  • تغطي الـ fingerprint الـ tools الخاصة بالـ agent نفسه والـ model والتعليمات الخاصة به، وليس الـ tools التي تضيفها subagents وskills. للـ sub-agent الذي يتوقف على approval fingerprint خاصة به في الـ snapshot المتداخلة. وعند الاستئناف، يُقارَن كل مستوى متوقف — الـ lead، والـ sub-agent، وsub-agent تابع لذلك الـ sub-agent — بتعريفه الحالي من subagents، تحت onAgentDrift الخاص بالـ lead. مع 'warn' يحمل حدث agent.drift الحقل subagent. وعندما يرفض فحص sub-agent، تعود approval الـ lead وcheckpoint الـ'awaiting-approval' الخاص به إلى مكانهما، فيمكنك إصلاح الـ sub-agent والحسم من جديد. أما remote sub-agent فلا يُقارَن: يبقى توقفه محفوظًا لدى الطرف البعيد.
  • الـ run الذي يستأنف بعد approval يكمل بالتعليمات التي بدأ بها (فهي في الـ transcript الخاص به)، فتسجّل الـ checkpoints اللاحقة التعليمات نفسها.

متقدم: executor API

createAgent() مبنية فوق AgentExecutor، الذي يبقى متاحًا عندما تريد التحكم في التوصيل بنفسك: الـ provider والـ ToolRegistry والـ stores واستدعاءات الـ resume كلها صريحة (انظر executor API). يذكر كل snippet أدناه استدعاء createAgent() المقابل له. AgentExecutor.execute() مع sessionId وcheckpointStore تعادل agent.send(message, { sessionId }):
وهي ترمي SessionAwaitingApprovalError على session متوقفة، كما تفعل send():
الدالة المصدّرة resumeAfterApproval() هي التي تستدعيها agent.approvals.resolve():
AgentExecutor.fork() تعادل agent.fork()؛ وexecute() مع input: [] على sessionId الـ fork تعادل agent.resume(fork.sessionId):

التوافق مع البيانات المخزنة

  • الـ checkpoints المكتوبة قبل وجود status تُعامَل كـ'in-progress' (قبل هذا التغيير، كانت الـ runs المنتهية تحذف الـ checkpoint الخاص بها، فلم يكن يُحفظ إلا الـ runs غير المكتملة).
  • الـ sessions المحفوظة قبل أن يحتفظ الـ store بـ history يكون الـ history الخاص بها فارغًا حتى الـ save التالي.
  • الـ approval snapshots المكتوبة قبل وجود remainingToolCalls تُستأنف كما كانت: الـ calls التي تلي المتوقفة لا تعمل. تأخذ كل واحدة منها نتيجة خطأ تذكر أنها لم تعمل، فيبقى الـ transcript صالحًا.

القيود

  • يعرّف sessionId محادثة منطقية واحدة. استدعاءات agent.send() / agent.stream() المتزامنة بنفس sessionId على store واحد للـ agent تعمل بالتتابع، بترتيب الاستدعاء، في هذه الـ process. أما processان (أو store objectان على البيانات نفسها) على الـ id نفسه في الوقت نفسه فيرفضهما الـ run lease بـLOUSHO_SESSION_BUSY (best effort على KV، انظر Run leases)؛ ومع store مخصص لا يملك leases، يفوز آخر save.
  • يتكوّن id الـ run (sessionId الخاص بـsend() / stream()) من 1 إلى 200 حرف من الحروف والأرقام و_ و- و.، ولا يبدأ ولا ينتهي بـ.، على كل store، ولا يجوز أن ينتهي بـ.turn-<n> أو .paused (مفاتيح الـ checkpoint الخاصة بالـ session) أو .fire (حجز الإطلاق الخاص بـ schedule). وأي شيء آخر يفشل بـLOUSHO_SESSION_ID_INVALID. أما id الـ session (agent.session({ id })، وsessionId في الـ routes) فقاعدته أشد: من 1 إلى 128 حرفًا من A-Za-z0-9_-، بدون ..
  • إذا استدعيت resumeAfterApproval() (الدالة التي تقف خلف agent.approvals.resolve()) بدون checkpointStore، تحتفظ الـ session بعلامة 'awaiting-approval' وتظل استدعاءات send() (أو execute()) اللاحقة ترمي SessionAwaitingApprovalError؛ مرّر الـ store (أو احذف الـ checkpoint). تمرّره agent.approvals.resolve() نيابةً عنك.
  • لدى Workers KV eventual consistency عبر المواقع — انظر النشر لتفاصيل هذا التحفّظ.
  • يُحفظ إنفاق الـ sub-agent الذي كان ما زال يعمل عندما تعرّض الـ lead لـ crash فقط للـ sub-agents التي تعمل داخل الـ process، وفق آخر استدعاء model أو نتيجة tool لديه: يبلّغ الـ remote sub-agent عن الـ usage الخاص به عندما ينتهي، فلا تُحتسب استدعاءات المنقطع منها، والـ sub-agent الذي يعمل في الخلفية ويظل يعمل بعد أن يتوقف الـ lead أو ينتهي لا يكتب في checkpoint الـ lead. ولا تُفحص حدودهم مقابل usage الـ sub-agent إلا عندما يعود.