الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
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().
الـ sessions طبقة رقيقة: تحتفظ الـ session بسجل المحادثة وتسلّمه إلى الـ executor في كل turn. ودون checkpoint store، لا تُحفظ الـ turn إلا عند اكتمالها، لذا يُضيّعها crash في منتصفها؛ انظر القسم التالي.

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

أعطِ الـ agent store يحتوي على 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 محفوظًا لآخر turnHistoryLimit turns أُجري لها 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:
تُجري كل turn الـ commit عبر 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 أيضًا.
يجب أن تطابق معرّفات الـ sessions النمط ^[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 هو الذي ينجح):
في كل اسم ملف، يُكتب الحرف الـ uppercase في المعرّف كـ ^ يليه الحرف 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 }:
وأي object يملك الدوال الثلاث لجزء معيّن يعمل مكانه أيضًا: SessionStore على Redis، أو CheckpointStore مبني على KV في Cloudflare Workers (يستخدم الـ Worker المولَّد KVCheckpointStore، انظر النشر). يخزّن SqliteStore الثلاثة في ملف database واحد، باستخدام node:sqlite المدمج في Node (دون native dependency؛ يتطلب Node 22.13 أو أحدث، ولا يُعاد تصديره من الـ root entry، لذا لا يحمّله استيراد الـ SDK أبدًا):
مع الـ executor مباشرةً، مرّر 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 في أدوات مساحة العمل.
ولكي تُجري fork لـ run واحد بدأ بـ agent.send(message, { sessionId })، من الـ history الخاص بالـ checkpoints، استخدم agent.fork() بدلًا من ذلك (انظر fork and replay).