Sessions وحالة المحادثة

افهم لماذا الـ Session أكثر من سجل محادثة

تخيّل أن المكتبة عرضت ثلاثة مواعيد، ثم اختار المستخدم واحدًا بعد عشر ثوانٍ. يصل Selection في طلب جديد إلى خادمك. لكي تتابع العملية، يجب أن تتذكر المكتبة أي قائمة عُرضت، والقيم الأصلية لعناصرها، ومتى تنتهي صلاحيتها. هذه معلومات تحفظها الـ Session، وليست مجرد سجل نصوص المحادثة.

يربط sessionId الطلب الجديد بالحالة المحفوظة. لذلك لا تولّد ID جديدًا لكل رسالة في المحادثة نفسها، ولا تشارك الـ ID بين مستخدمين. خادمك يحدد أي Session يملكها المستخدم.

ابدأ بنسخة Runtime تنشئها عند تشغيل خادمك وتحتفظ بها. مخزن الذاكرة الافتراضي يكفي لتجربة داخل عملية تشغيل واحدة، لكنه يفقد البيانات عند إعادة تشغيلها.

إذا شغّلت عدة نسخ من الخادم، فقد يصل طلب Selection إلى نسخة لا تملك القائمة السابقة. عندها تحتاج إلى مخزن Sessions مشترك يلتزم بقواعد SessionStore أدناه. إضافة Redis بالاسم لا تكفي؛ طريقة تنسيق الطلبات المتزامنة جزء من صحة التكامل.

حدّد سلوك التخزين قبل التوسّع

لا يكفي سجل key/value مشترك. يجب ألا تقرأ محاولتا Confirmation متزامنتان الموافقة نفسها قبل استهلاكها. يجب أن تضمن transact() تنفيذ العمليات بالتتابع لكل Session، بحيث تكتمل العملية غير المتزامنة كلها، بما فيها انتظار الشبكة، قبل بدء العملية التالية. ولا يجوز أن ينتهي قفل العملية بصمت بينما ما زالت تعمل.

تُحفظ State الخاصة بالـ Session وبيانات الاعتماد في مخزنين منفصلين. مشاركة SessionStore وحدها لا تجعل الـ Token المحفوظ لدى Worker متاحًا لدى Worker آخر. مرّر Token المصرّح بها في كل متابعة، أو وفّر مخزن Tokens المشترك والمشفّر كما يشرح دليل Auth.

اختبر نسختي Runtime بمخزن مشترك واستدعاءات Confirmation متزامنة، وتأكد من كتابة واحدة. واختبر الانتهاء وتغيّر Config وانقطاع worker. إذا فشل التخزين، عالج العطل وتحقق من نتيجة العملية قبل تكرار Side Effect.

ما الذي تحتفظ به الـ Session؟

تخزّن SessionStateV2:

• state، حالة Runtime الصريحة.
• history، عددًا محدودًا من رسائل المستخدم والمساعد.
• facts، قيمًا مع مصادرها وTTL اختياري.
• stack، execution frames للـ Dependencies.
• selection معلّقًا.
• confirmation معلّقًا.
• context التطبيق المضيف بعد تنقيحه.
• references المنشورة من عناصر API المختارة.
• configHash.
• وقت انتهاء الصلاحية وإجمالي الرسائل طوال عمر الـ Session.

قواعد transact()

الدالة الأهم في SessionStore ليست get() أو set()، بل:

transact<T>(id: string, operation: () => Promise<T>): Promise<T>

يجب تنفيذ العملية غير المتزامنة كاملةً بالتتابع للـ Session الواحدة عبر جميع نسخ الـ Runtime التي تشترك في الـ Store.

تنفيذ Redis البسيط الذي يقوم بما يلي:

GET session
...
SET session

دون distributed lock قابل للتجديد وآلية fencing، لا يكفي لضمان صحة العمل عبر عدة instances.

التخزين في الذاكرة

import { MemorySessionStore } from "agento-runtime";

مناسب لـ:

• التطوير المحلي.
• الاختبارات.
• النشر ضمن process واحدة، حيث تشترك instances في كائن المخزن نفسه.

ولا يكفي للتوسع الأفقي عبر عدة processes.

واجهة المخزن المخصص

interface SessionStore {
  get(id: string): Promise<SessionStateV2 | null>;
  set(id: string, state: SessionStateV2): Promise<void>;
  delete(id: string): Promise<void>;
  touch(id: string, expiresAt: number): Promise<void>;
  transact<T>(id: string, operation: () => Promise<T>): Promise<T>;
}

انتهاء الصلاحية وتغيّر الإعدادات

تصبح الـ Session غير صالحة عند انتهاء TTL، أو إذا لم يعد configHash المخزّن يطابق الـ Config التي جهّزها الـ Runtime. يمسح AGENTO الحالة غير المتوافقة، بدل محاولة استكمال عملية بقواعد مختلفة.

علامة التنفيذ المنقطع

إذا وجد AGENTO Session مخزّنة في حالة EXECUTING، يعتبر نتيجة العملية السابقة ذات الأثر غير محسومة، ولا يعيد تنفيذها تلقائيًا. تحقّق من النتيجة أولًا.

سياق التطبيق المضيف

مرّر بيانات موثوقة خاصة بالطلب أو الـ Session:

context: {
  tenant: { id: "tenant_42" },
  locale: "ar-PS"
}

ثم اربطها صراحةً:

X-Tenant-Id:
  source: session
  path: $.tenant.id

لا تضع access Tokens في السياق العادي؛ استخدم auth.token.