agent.send(text) هو turn واحد فقط: كل call يبدأ من سجل فارغ.
أما الـ session (جلسة) فهي محادثة من أكثر من turn: تحتفظ بسجل المحادثة
وتمرّره إلى الـ model مع كل send().
انظر أيضًا: إيقاف وإعادة تشغيل واستئناف، وهو دليل قصير من البداية إلى النهاية.
تترك لك الأمثلة في هذه الصفحة تعريف بعض الأسماء:providerهو أيLLMProvider(ودون اتصال:createMockProvider()).
كائن الـ session
استدعاءات
send() المتزامنة على الـ session نفسها تُصَفّ وتُنفَّذ
واحدًا تلو الآخر بترتيب الاستدعاء، فلا يتداخل سجل المحادثة أبدًا.
يحدد agent.session({ id, turnPolicy }) سلوك send() أو stream()
عندما تكون هناك turn قيد التشغيل أو تنتظر البدء:
'wait'(الافتراضي): ينتظر ويُنفَّذ كـ turn مستقلة، كما سبق.'queue': ينضم الـ input الخاص به إلى تلك الـ turn، مثلrun.enqueue(): يُضاف بعد نتائج الـ tools في الخطوة الحالية، ويراه call الـ model التالي في الـ turn. يُرجع الـ call نتيجة تلك الـ turn (ولا يسري الـsignalالخاص به على الـ turn)، ويحتوي سجل المحادثة المحفوظ عند انتهاء الـ turn على رسالة الـ user التي دخلت الـ queue في موضعها. أماstream()المنضم فلا يُصدر إلاrun.doneالخاص بالـ turn؛ وتُبَث events الـ turn، ومنهاinput.queuedوinput.applied، على الـ run الذي بدأها. إذا انتهت الـ turn قبل أن تتمكن من أخذ الـ input (اكتملت، أو توقفت، أو أُلغيت)، يُنفَّذ الـ call كـ turn تالية في النهاية على أي حال — إلا في durable session لا تزال الـ turn المتوقفة فيها pending: هنا يستأنفها الـ call أولًا، ويرميSessionAwaitingApprovalErrorإذا كانت لا تزال تنتظر الـ approval (بُتّ فيها بـagent.approvals.resolve()). وإذا فشلت الـ turn، يرمي الـ call الـ error نفسه؛ وفي durable session يبقى الـ input في checkpoint الـ turn ويطبّقهresume().'steer': مثل'queue'، لكن الـ input ينضم عبرrun.steer(): إذا لم يكن call الـ model في الـ turn قد أصدر أي شيء بعد، فإنه يُلغى ويُعاد من البداية مع الرسالة الجديدة، ولا تُنفَّذ الـ tool calls الخاصة بالـ turn التي لم تبدأ بعد. وفيما عدا ذلك ينتظر نقطة الأمان التالية، مثل'queue'. يُرجع الـ call نتيجة الـ turn، وتسري الـ fallbacks نفسها.
vendor/ في اسم الـ model هي التي تحدد الـ provider؛ ومع OpenRouter استخدم
openrouter/<vendor>/<model> (مثلًا openrouter/openai/gpt-4o-mini).
send() وstream() نصًا (string)، أو content parts ([{ type: 'text', ... }, { type: 'image', ... }]، وهي رسالة user واحدة)، أو Message[]؛ وتحتفظ الـ stores بالـ parts، انظر المدخلات متعددة الوسائط.
إذا رمى send() (error من الـ provider، أو tool ترمي
PropagatingToolError) فإنه يترك سجل المحادثة كما كان تمامًا قبل الـ call.
أما send() الذي يُلغى بـ signal (زر Stop مثلًا) فيحتفظ بما قاله
الـ user والـ model حتى تلك اللحظة، لكي يبقى السياق متاحًا لـ GET /chat/:id
وللـ turn التالية:
- رسالة الـ user، بشرط أن يكون الـ model قد استُدعي (الـ signal الملغى قبل أول call للـ model يتخلّص من الـ turn كلها)؛
- الـ turn حتى آخر tool call نُفِّذ (الـ tool calls الخاصة بالـ assistant ونتائجها؛ وتأخذ الـ calls التي في الدفعة نفسها ولم تبدأ نتيجة “cancelled”)، لذا يستحيل أن يضيع side effect مثل refund من السجل؛
- الرد الذي بثّه الـ model حتى توقفه، كرسالة assistant
تحمل
metadata: { interrupted: true }(stream()وحده هو الذي يبث؛ أماsend()العادي فليس له رد جزئي).
send() الملغى finishReason: 'aborted'، مثل agent.send().
ويحتسب الـ usage الخاص به call الـ model الذي توقف، بتقدير من الـ request
والنص المبثوث إذا لم يُبلغ الـ provider بشيء، لكي
لا يُحتسب limits.maxCostUsd الخاص بالـ session أقل من الحقيقة. ويستحيل أن يحتوي سجل المحادثة المحفوظ
على turn للـ assistant فيها tool calls دون نتائج الـ tools المقابلة.
إذا توقف send() عند tool فيها needsApproval فإنه يُرجع
finishReason: 'awaiting-approval'. بعد ذلك يُكمل agent.approvals.resolve({ id, approved })
الـ run كـ turn تالية في الـ session، فينضم الـ tool call ونتيجته
والإجابة النهائية إلى سجل المحادثة (انظر
approvals).
يضع agent.session({ id, limits }) budgets على جميع turns الـ session
(مثلًا { maxCostUsd: 1 })، وتُحتسب من الـ usage المحفوظ مع
سجل المحادثة؛ أما createAgent({ limits }) فيقيّد كل turn على حدة. انظر
الميزانيات.
Streaming a session turn
session.stream(input, { signal }) هو agent.stream() لكن لمحادثة:
يُرجع الـ AgentRun نفسه (typed events مع promise اسمه result، انظر
streaming)، لكن الـ turn ترى سجل المحادثة حتى تلك اللحظة
وتنضم إليه.
- يبني قائمة الرسائل نفسها التي يبنيها
send()ويُصَفّ خلف الـ calls السابقة على الـ session (يمكنك الخلط بينsend()وstream()). - عندما ينتهي الـ run، تُحفظ رسالة الـ user الجديدة ومخرجات الـ run
تمامًا كما يحفظها
send()، وبعد ذلك فقط يُسلَّمrun.done. أي أنه عندما تنتهي حلقةfor await، أو يُرجعrun.result، يكون سجل المحادثة مكتملًا. وتحمل الـ events الـrunIdالخاص بالـ handle المُرجَع. - الـ run الفاشل يترك سجل المحادثة كما كان قبل الـ call، مثل
send(). أما الـ run الملغى (بـsignal، أو عندما تخرج من الحلقة مبكرًا) فيحتفظ برسالة الـ user والـ tool calls التي نُفِّذت والرد المبثوث حتى تلك اللحظة (مُعلَّمًا بـmetadata.interrupted)، مثلsend()الملغى. والـ run الذي كان قد انتهى أصلًا عند مغادرة الحلقة يُحفظ. والـ run الفاشل يُغلق الـ stream بـerrorوrun.done(finishReason: 'error')، ويرميrun.result. ويشمل ذلك الـ store الذي يفشل في الـ load أو الـ save: وعندئذ لا يكون للـ turn حدثrun.start. - الـ run الذي يتوقف عند tool فيها
needsApprovalينتهي بـapproval.requestedوrun.done('awaiting-approval')، تمامًا كما يُرجعsend()، ويحتوي سجل المحادثة على الـ turn حتى موضع التوقف. ويُكملهاagent.approvals.resolve()كـ turn تالية في الـ session. ولا يسري callback الخاص بـapproveعلى الـ streams، مثلagent.stream().
Two kinds of conversation id
agent.session({ id }) وagent.send(msg, { sessionId }) محادثتان مختلفتان.
لدى الـ SDK طريقتان لحفظ محادثة تحت معرّف، ولا تتشاركان
التخزين نفسه:
استخدم طريقة واحدة لكل معرّف. المعرّف المستخدم بالطريقتين يحتوي على محادثتين لا علاقة بينهما:
الـ turn المرسلة بإحدى الطريقتين لا ترى الـ turns المرسلة بالطريقة الأخرى، و
GET /chat/:id يعرض سجل محادثة الـ session فقط. يبحث agent.resume(id)
أولًا عن run خاص بـ send({ sessionId })، وإذا لم يجده، يستأنف عندئذ فقط
الـ turn الـ pending الخاصة بالـ session، لذا إذا وُجد الاثنان فإنه يُكمل الـ run ويترك
turn الـ session في حالة pending (أكملها بـ agent.session({ id }).resume()).
وتعمل الـ prompt schedules كـ runs من نوع send({ sessionId }) (انظر
الجداول الزمنية)، لذا اقرأ تقارير الـ schedule
من store.checkpoints، لا من GET /chat/:id.
Durable sessions
أعطِ الـ agentstore يحتوي على checkpoints، فيُحفظ checkpoint لكل turn في الـ session
بعد كل رد من الـ model وكل نتيجة tool، باستخدام
آلية durable execution. والـ turn التي يقطعها
crash، أو فشل في كتابة checkpoint، أو PropagatingToolError، يمكن
إكمالها لاحقًا، في process أخرى:
- يقبل
createAgent({ store })أيAgentStore({ sessions?, checkpoints?, approvals? }، انظر Choosing a store): يضعagent.session({ id })سجل محادثته فيstore.sessionsوالـ checkpoints الخاصة به فيstore.checkpoints، ويحتفظstore.approvalsبتوقفات الـ approval. ويتقدّم الـstoreالخاص بالـ session (أيSessionStore، أو كائن{ sessions, checkpoints }) وcheckpointStoreعلى store الـ agent، جزءًا بجزء. agent.resume(id)هو نفسهagent.session({ id }).resume()، والفرق أنه يُكمل أولًا الـ run الذي بدأ بـagent.send(message, { sessionId: id })(انظر durable execution و نوعا الـ id).- تعمل كل turn بـ
sessionId: '<session id>.turn-<n>'(حيثnهو طول سجل المحادثة لحظة بدء الـ turn)، لذا تجد الـ process الجديدة الـ turn المنقطعة دون أي عمل تتبّع إضافي. والـ turn المكتملة تنضم إلى سجل المحادثة، تمامًا مثلsend()العادي، ويُحذف الـ checkpoint الخاص بها. معرّف الـ turn هذا مجرد مفتاح للـ checkpoint: لا تزال الـ tools وneedsApprovalوقواعد الـ permissions والـ hooks الخاصة بالـ tool calls تأخذ معرّف الـ session نفسه كـctx.sessionId. يبقى الـ checkpoint history الخاص بالـ turn محفوظًا لآخرturnHistoryLimitturns أُجري لها commit (الافتراضي 10،agent.session({ id, turnHistoryLimit }))، لكي يستطيعagent.fork('<id>.turn-<n>', { fromStep })إجراء fork منها؛ وتُحذف histories الـ turns الأقدم مع commit الـ turns الجديدة (كل entry في الـ history يحتوي على نسخة من سجل المحادثة كله، فلو احتُفظ بـ history كل الـ turns لنما الـ store بمربع طول المحادثة)، حتى لو استخدمت كل turn كائن store أو process جديدة. والـ history الموجود خارج النافذة أصلًا في الـ store - من إصدار أقدم، أو تحتturnHistoryLimitأكبر - يُحذف هو أيضًا على مدار الـ commits التالية، بحدّ 32 turn في كل commit، الأقدم أولًا؛ والـ process التي تُجري commit لـ turn واحدة فقط تُنظّف أقدم 32، وfileStore(dir).prune()/SqliteStore.prune()يحذفان الباقي. أماsession.fork()فيعمل من سجل المحادثة ولا يتقيّد بهذا الحد. - أثناء التشغيل، تحتفظ الـ turn بـ run lease على الـ checkpoint الخاص بها (انظر
durable execution): أي
send()على الـ session نفسها من process أو replica أو كائن store آخر يفشل بـLOUSHO_SESSION_BUSYقبل أن يشغّل أي شيء، بدلًا من أن يستأنف الـ turn الجارية ويشغّل الـ tool calls الخاصة بها مرة ثانية. - يُكمل
resume()الـ turn عبر مسار الـ resume في الـ executor (input: []): لا تُنفَّذ مرة أخرى الـ tool calls التي سُجِّلت نتائجها، ولا يُطلب رد الـ model المسجَّل مرة أخرى. لكن الـ tool التي كانت قيد التشغيل عندما توقفت الـ process تُنفَّذ مرة أخرى (at-least-once، انظر durable execution). - يستأنف
send()وstream()الـ turn الـ pending أولًا، ثم يرسلان الرسالة الجديدة، فيرى الـ model الـ turn مكتملة (لا تُبَث events الـ turn المستأنفة). استخدمpending()للتحقق أولًا، أوdiscardPending()لكي تتخلّص من الـ turn غير المكتملة. - الـ turn التي تفشل تسجّل الـ error وعدد المحاولات على الـ checkpoint الخاص بها
(
lastErrorوattempts). إذا كان الـ error لن يزول بإعادة المحاولة (400 من الـ provider مثل تجاوز طول السياق، أو فشل في الـ auth)، فإنsend()/stream()التالي لا يعيد الـ turn: بل يفشل بـLOUSHO_SESSION_TURN_FAILED. استدعِdiscardPending()لكي تتخلّص من الـ turn، أوresume()لكي تعيد المحاولة بعد إصلاح السبب. أما أنواع الفشل الأخرى (crash، أو 5xx، أو error في الشبكة) فلا يزالsend()التالي يستأنفها. وينطبق ذلك أيضًا على turn فشل فيها أول call للـ model: لم يحفظ الـ run أي checkpoint بعد، لذا تحتفظ الـ session بالـ input الخاص بالـ turn كـ turn pending (يُبلغpending()أنهاin-progress) وتعيد تشغيلها من هذا الـ input. - الـ turn التي تتوقف عند tool فيها
needsApprovalتبقى في الـ checkpoint الخاص بها، لا في سجل المحادثة، حتى تكتمل. وأثناء انتظارها، يرميresume()وsend()وstream()الخطأSessionAwaitingApprovalError(ومعهapprovalId)، ويُكملagent.approvals.resolve({ id, approved })الـ turn في هذه الـ session. وبعد restart، يُكملها أيضًاagent.approvals.resolve()أوstreamResolve()من الـ process الجديدة: يجد الـ agent الـ session من سجل التوقف (لمعرّفات الـ session التي تحتوي على حروف وأرقام و_و-)، فلا داعي لفتح الـ session أو استدعاءresume()أولًا. وأعطِ كلا الـ agents الـstoreالدائم نفسه (أوapprovalStore). - يُرجع
resume()نتيجة الـ turn المكتملة؛ ولا يبث، وstream()أيضًا لا يبث الـ turn الـ pending التي يُكملها أولًا. ولكي تعرض تقدّم turn مستأنفة، سجّلsession.on(listener)قبل الـ call (أو مرّرcreateAgent({ onEvent })): تصله أحداثAgentEventالخاصة بالـ turn فور حدوثها. - الـ turn المتوقفة تقفل معرّف الـ session: تسجّلها الـ session تحت
<id>.pausedفي الـ checkpoint store، لذا يُرفضagent.send(message, { sessionId: id })، وagent.stream()بالـsessionIdنفسه، وأي كائن session على سجل محادثة مختلف (store آخر، أو سجل بطول مختلف) بالخطأSessionAwaitingApprovalError(LOUSHO_SESSION_AWAITING_APPROVAL) أيضًا، و يُبلغpending()الخاص بها عن التوقف. بُتّ في الـ approval، أو تخلّص من الـ turn بـagent.session({ id }).discardPending()، لكي تقبل الـ session turns جديدة مرة أخرى. - الـ turn الملغاة يُحذف الـ checkpoint الخاص بها؛ وما احتفظت به (رسالة الـ user،
والـ tool calls التي نُفِّذت، والرد المنقطع) ينضم إلى سجل المحادثة، كما يحدث
دون checkpoint store. ويحذف
clear()الـ turn الـ pending أيضًا، والـ checkpoint history الخاص بكل turn، لذا لم يعد ممكنًا إجراء fork للـ turns المحذوفة.
Stores
يحتفظSessionStore بسجلات المحادثات بين الـ calls:
saveIf إذا كان الـ store يوفّرها، مع
transcriptRevision(<the transcript the turn started from>). فإذا أنهت عمليتان (أو
كائنا store على البيانات نفسها) turn على الـ session نفسها في اللحظة
نفسها، لا يمكن أن تُجري الاثنتان commit: تنجح إحداهما، ويرمي send() الخاص بالأخرى
LOUSHO_SESSION_BUSY. وتطبّقها MemorySessionStore وFileSessionStore (ملف
<id>.json.lock يُنشأ بشكل حصري؛ والـ lock الأقدم من staleLockMs،
الافتراضي 10 ثوانٍ، يُستولى عليه) وSqliteStore.sessions (transaction واحدة
BEGIN IMMEDIATE). أما الـ store الذي لا يوفّرها، مثل KVStore.sessions (فالـ KV
لا يدعم compare-and-swap)، فيُجري load ومقارنة وsave بأفضل جهد، وقد
يتدخّل بينها writer في process أخرى، فتضيع turn واحدة.
MemorySessionStore(الافتراضي، store جديد لكل session) يبقى طالما الـ process تعمل. شارك الـ instance نفسه بين الـ sessions لكي تجدها بالمعرّف.- يكتب
FileSessionStore(dir)ملف JSON واحدًا لكل session (<dir>/<id>.json)، كتابةً atomic (ملف مؤقت ثم rename)، وينشئdirعند أول save. وكل حرف uppercase في المعرّف يُكتب كـ^يليه الحرف lowercase (Alice->^alice.json)، لذا تأخذ المعرّفات التي تختلف في حالة الحروف فقط ملفات مختلفة على Windows وmacOS أيضًا.
^[A-Za-z0-9_-]{1,128}$ (فهي تصبح أسماء ملفات، ولذلك
يُرفض ../x وa/b بـ error يوضّح السبب). طبّق
SessionStore بنفسك لكي تضع سجلات المحادثات في database أو Redis.
يحتوي AgentStore على جزء رابع اختياري إلى جانب sessions وcheckpoints
وapprovals: وهو tokens، أي access وrefresh tokens الخاصة بـ OAuth للـ tools
والاتصالات، وتخزّنها الـ stores من نوع file وSQLite وKV مشفّرة (انظر
OAuth).
Choosing a store
لكلٍّ من الـ sessions وcheckpoints الخاصة بـ durable execution والـ approvals واجهة store (SessionStore وCheckpointStore وApprovalStore). اختر
الـ implementation بحسب مكان تشغيل الـ process:
كلٌّ منها جزء من
AgentStore: مرّرها معًا هكذا
createAgent({ store: { sessions, checkpoints, approvals } }). وmemoryStore()
وfileStore(dir) وSqliteStore وKVStore هي AgentStores جاهزة. وللملفات
العادية، يكتب fileStore(dir) ملف JSON واحدًا لكل session وcheckpoint وapproval
pending تحت dir، ويُكتب كلٌّ منها في ملف مؤقت، ثم يُجرى له flush على القرص، ثم rename
إلى مكانه (فلا يترك crash أو انقطاع كهرباء نصف ملف أبدًا). على Windows، يفشل الـ rename فوق ملف، أو قراءة ملف،
مفتوح لدى writer أو reader آخر لحظيًا بـ EPERM أو EACCES أو
EBUSY؛ ويعيد fileStore() وFileSessionStore المحاولة مع backoff قصير (نحو
1.3 ثانية إجمالًا) ثم يفشلان بـ LOUSHO_STORAGE_FAILED. ولا تزال الـ saves المتزامنة على
الملف نفسه تنتهي بواحد منها فقط (آخر rename هو الذي ينجح):
^ يليه
الحرف lowercase (Alice -> sessions/^alice.json): فأنظمة الملفات الافتراضية
في Windows وmacOS لا تفرّق بين حالة الحروف، ويجب ألا يتشارك alice وAlice
سجل المحادثة نفسه. والمعرّف الذي لا يحتوي على حروف uppercase يبقى باسمه العادي. والملف
الذي حُفظ بإصدار أقدم تحت اسم بحروف مختلطة (Alice.json) لا يزال يُقرأ
للمعرّف نفسه تمامًا، ويُنقل إلى اسمه الجديد في الـ save التالي. والمعرّف الذي
سينتج اسم ملف طويلًا جدًا بعد الـ encoding (session id كله uppercase بطول 128 حرفًا
مضافًا إليه .turn-<n>)، أو اسم جهاز في Windows (nul، com1)، يُخزَّن
باسم ~<prefix>~<hash>.json بدلًا من ذلك.
بجانب كل ملف checkpoints/<id>.json ملف checkpoint-history/<id>.json: وهو الـ history المحدود للـ checkpoint، الأقدم أولًا. وتُنشأ المجلدات عند أول كتابة، لذا لا يظهر approvals/ (وoauth/) إلا بعد أول approval pending (أو sign-in).
البتّ في approval من fileStore آمن عبر الـ processes (caller واحد فقط
يأخذ السجل، والـ claim الذي تركه resolver متعطّل يُستولى عليه بعد
دقيقة)؛ وتُجري الـ session الـ commit للـ turns الخاصة بها بـ compare-and-swap تحت ملف lock
(sessions/<id>.json.lock)، والـ run الجاري الذي يُحفظ له checkpoint يحتفظ بالـ run lease الخاص به
في leases/<id>.json (انظر durable execution).
وإذا كانت لديك processes كثيرة تتشارك store، فإن SqliteStore هو الخيار الأمتن.
يحذف fileStore(dir).prune({ olderThanMs }) ما كانت آخر كتابة له قبل أكثر من
olderThanMs، مثل SqliteStore.prune(): سجلات المحادثات والـ checkpoints وملفات
الـ checkpoint history، بالإضافة إلى sign-ins الخاصة بـ OAuth الـ pending المنتهية. ويبقى الـ run المتوقف على
approval pending، مهما كان قديمًا (الـ checkpoint الخاص به والـ history الخاص به وسجل محادثة
الـ session الخاصة به)، وتبقى أيضًا الـ approvals الـ pending وOAuth tokens. ويُرجع
الأعداد، { sessions, checkpoints, checkpointHistory, oauthPending }:
SessionStore
على Redis، أو CheckpointStore مبني على KV في Cloudflare Workers (يستخدم الـ
Worker المولَّد KVCheckpointStore، انظر النشر).
يخزّن SqliteStore الثلاثة في ملف database واحد، باستخدام
node:sqlite المدمج في Node (دون native dependency؛ يتطلب Node 22.13 أو أحدث، ولا
يُعاد تصديره من الـ root entry، لذا لا يحمّله استيراد الـ SDK أبدًا):
store.checkpoints كـ checkpointStore و
store.approvals كـ approvalStore؛ انظر executor API.
- يُنشأ المجلد إذا لم يكن موجودًا. والـ schema لها versioning عبر
PRAGMA user_versionوتُجرى لها migration عند الفتح؛ وتُرفض الـ database المكتوبة بإصدار أحدث. - وضع WAL وانتظار قصير للـ lock مع إعادة المحاولة (نحو 5 ثوانٍ إجمالًا، ثم
LOUSHO_STORAGE_BUSY) يتيحان لعدة processes أن تتشارك الملف. ولا يستطيع إلا واحد منها البتّ في الـ approval. انظر مشاركة ملف SQLite. - تُخزَّن الـ checkpoints وsnapshots الخاصة بالـ approval كـ JSON معتم لا يُفسَّر محتواه، لذا تمرّ الحقول الجديدة في round-trip دون تغيير.
- يزيل
prune()الـ sessions والـ checkpoints التي لم تُحدَّث خلالolderThanMs، والـ approvals التي حُسمت قبل تلك المدة وsign-ins الخاصة بـ OAuth الـ pending المنتهية؛ أما الـ approvals التي لم تُحسم بعد وOAuth tokens فتبقى، وكذلك الـ turn المتوقفة على approval لم تُحسم بعد (الـ checkpoint الخاص بها وسجل محادثة الـ session)، مهما كانت قديمة. والبتّ في approval حُذفت الـ turn المتوقفة الخاصة بها على أي حال يفشل بـLOUSHO_APPROVAL_ORPHANEDدون تشغيل الـ tool. - الملف الذي ليس database خاصة بـ SQLite يفشل بـ error يذكر المسار؛
واستخدام الـ store بعد
close()يرمي error واضحًا.
مشاركة ملف SQLite
هذا هو القسم الوحيد الذي تربط إليه الصفحات الأخرى.- مدعوم: عدة processes (مثلًا نسختا replica من Docker على named volume واحد، أو
سيرفر وCLI) على host واحد، تتشارك ملف SQLite واحدًا على قرص محلي.
يعمل الملف بوضع WAL، وكل turn في session تحتفظ بـ
run lease، لذا يمكن للـ replicas أن تتبادل
الرسائل على الـ session نفسها. والكتابة على session تشغّلها process أخرى
تفشل بـ
LOUSHO_SESSION_BUSY؛ ويردّ عليهاPOST /chatوالـ channels بـ409وهيدرRetry-After، فأعد المحاولة. - غير مدعوم: ملف SQLite على filesystem شبكي (NFS، EFS، SMB)، لأن SQLite
لا تستطيع الاعتماد على الـ locking الخاص به، ولا عدة hosts. لعدة hosts،
طبّق
SessionStoreوCheckpointStoreوApprovalStoreعلى database مشتركة مثل Postgres أو Redis. لا يتضمن الـ SDK أي store شبكي. - الساعات والـ PIDs: تُحتسب الـ leases بساعة كل process على حدة، لذا اجعل ساعات الـ replicas متزامنة (NTP). ولا يُستولى على الـ run المتعطّل مبكرًا إلا عندما يثبت أن الـ process الخاصة به غير موجودة على الـ host نفسه (يُفحص الـ boot id والـ PID namespace ووقت بدء الـ process)؛ وفيما عدا ذلك ينتظر من 30 إلى 60 ثانية حتى تنتهي الـ lease. انظر Run leases.
تعليمات المشروع
ليست جزءًا من الـ sessions، لكنهما يُطلبان معًا كثيرًا: انظر “Project instructions” في الإعدادات لكي تعطي الـ agent ملفAGENTS.md الخاص بالـ repo لديك.
Forking a session
تسردsession.history() خطوات الـ session، ويبدأ session.fork({ fromStep }) session جديدة من أي خطوة منها، فتستطيع تجربة اتجاه آخر
دون أن تفقد المحادثة الأصلية:
- الـ step رد واحد من الـ model في سجل المحادثة: رسالة assistant،
مع رسائل الـ tools التي تردّ على الـ tool calls الخاصة به. وتُرجع
history(){ step, turn, messageIndex, text, toolCalls }لكل خطوة، الأقدم أولًا:stepمرقّمة من 1 على مستوى الـ session كلها (لا لكل turn)، وturnمرقّمة من 0، وmessageIndexهو index رسالة الـ assistant فيsession.messages، وكل tool call معهidوnameوargsبعد الـ parse (أو الـ string الخام إذا لم يكن JSON) وresult(محتوى رسالة الـ tool كنص، مُرمَّزًا بـ JSON كما رآه الـ model). والخطوات نسخ (copies). - تبدأ الـ turn عند كل رسالة user، لذا فإن
turnالخاص بالخطوة هو الـ index المبدوء من 0 لرسالة الـ user التي تردّ عليها، وهو الترقيم نفسه الذي يستخدمه workspace rewind. والـ input الذي أُضيف عبر queue أو steer داخل turn جارية (turnPolicy: 'queue'أو'steer') هو رسالة user أيضًا، لذا يبدأ turn جديدة فيhistory(). history()هو تاريخ سجل المحادثة الحالي: بعدsession.compact()تُرقَّم الخطوات من جديد بناءً على السجل بعد الـ compaction. وturn الـ durable التي لم تكتمل بعد ليست في السجل حتى الآن، لذا لا تُسرَد.- يحتفظ
fork({ fromStep })بالسجل حتى آخر رسالة tool في الخطوة شاملةً إياها؛ ولا يحتفظfromStep: 0بشيء. والخطوة الواقعة خارج0..history().lengthتُرفض بـLOUSHO_SESSION_STEP_NOT_FOUND، وتسرد رسالته النطاق الصحيح. - يستبدل
patch: { toolResult: { toolCallId, result } }نتيجة tool call واحد في السجل المحتفَظ به (“ماذا لو لم يجد البحث شيئًا؟”)، بالطريقة نفسها التي يعمل بهاpatchفيagent.fork(). - يُحفظ الـ fork في store الـ session نفسه، وهو session للـ agent نفسه بالـ
options نفسها (
storeوالـ checkpoints وlimitsوturnPolicyوcompaction، ووضع الصلاحيات الذي كانت عليه الـ session وقت الـ fork)، لذا يعمل الـ streaming والـ approvals والـ turns ذات الـ checkpoints كما في أيagent.session()، ويُكملهاagent.session({ id: fork.id, store })لاحقًا، حتى في process أخرى. ومعرّفه هوidإذا مرّرته، وإلا<id>-fork-<n>لأولnبدءًا من 1 ليس له سجل محادثة (وإذا كان المعرّف أطول من أن تُضاف إليه هذه اللاحقة،<start of id>-<8 hex of its hash>-fork-<n>، ويبقى في حدود 128 حرفًا). والـidالذي له سجل محادثة أصلًا (أو هو معرّف الـ session نفسه) يُرفض بـLOUSHO_SESSION_EXISTS. - تحتوي
messagesالخاصة بالـ fork على سجل محادثته فور عودةfork(). - لا يتغير سجل محادثة الـ session الأصلية ولا الـ checkpoints الخاصة بها.
- الـ budgets: يبقى الـ spend المسجَّل لـ
limitsعلى الرسائل المحتفَظ بها، لذا يبدأlimitsالخاص بالـ fork مما أنفقته الـ session عند نهاية آخر turn محتفَظ بها (تسجّل الـ turn إنفاقها على آخر رسالة فيها). - ينتظر
fork()الـ calls الموجودة في الـ queue، ويرميLOUSHO_SESSION_BUSYعندما تكون هناك turn قيد التشغيل. - يمكنك إجراء fork لـ session متوقفة. وتبقى الـ turn المتوقفة والـ approval الخاصة بها أو
ask_questionوالـ turn المنقطعة في durable session مع الـ session المصدر: لا تكون للـ fork أي turn pending، ولا يُكملagent.approvals.resolve()إلا المصدر، مرة واحدة. - المحادثة وحدها هي التي يُجرى لها fork. فالملفات التي كتبها الـ agent والـ side effects الأخرى للخطوات بعد نقطة الـ fork لا تُستعاد؛ ولكي تستعيد ملفات مساحة العمل، انظر قسم الـ rewind في أدوات مساحة العمل.
agent.send(message, { sessionId })، من
الـ history الخاص بالـ checkpoints، استخدم agent.fork() بدلًا من ذلك (انظر
fork and replay).