آگاهی از وضعیت نشست

وقتی چند نشست روی یک مسئله کار می‌کنند — مدیری که کار را به فرزندان واگذار می‌کند، انسانی که مستقیماً وارد نشست یک عامل اجرایی می‌شود، یا دو عامل که از طریق sessions_send هماهنگ می‌شوند — هر نشست درباره دیگران فرض‌هایی می‌سازد. به‌محض دخالت بازیگری دیگر، آن فرض‌ها منسوخ می‌شوند. آگاهی از وضعیت نشست سازوکاری است که این دخالت را تشخیص می‌دهد، یک‌بار نشست متأثر را مطلع می‌کند و راهی کم‌هزینه در اختیارش می‌گذارد تا پیش از اقدام، خود را به‌روز کند.

سه بخش با هم کار می‌کنند:

1. یک گزارش پایدار سیگنال‌ها تغییرات وضعیت منتخب را برای هر نشست ثبت می‌کند.
2. ناظران مکان‌نماهای مختص هر هدف را نگه می‌دارند و یک اعلان تجمیع‌شده درباره وضعیت منسوخ دریافت می‌کنند.
3. همگام‌سازی مجدد اختلاف دقیق را از طریق session_status با changesSince دریافت می‌کند.

گزارش سیگنال‌ها

وقتی یک نشست تحت نظارت به‌طور معناداری تغییر می‌کند، OpenClaw یک رویداد نوع‌دار را به پایگاه داده وضعیت مشترک (session_state_events) می‌افزاید. رویدادها حاوی فراداده و خلاصه‌ای یک‌خطی هستند — هرگز محتوای پیام را شامل نمی‌شوند.

هر رویداد بازیگر خود را (human، agent یا system) مشخص می‌کند. اجراهای فرزند لغوشده و زمان‌تمام‌شده به‌عنوان شکست ثبت می‌شوند و نتیجه دقیق (cancelled، timeout یا error) در داده رویداد حفظ می‌شود.

نسخه وضعیت یک نشست صرفاً بالاترین شماره توالی در گزارش آن است که در یک سرآیند پایدار مختص نشست ردیابی می‌شود و پس از هرس نیز باقی می‌ماند. ردیف‌های sessions_list، وقتی نشستی تغییرات ثبت‌شده داشته باشد، شامل stateVersion هستند؛ session_status همیشه آن را گزارش می‌کند.

نوع‌های فقط‌گزارشی برای تاریخچه همگام‌سازی مجدد وجود دارند، نه اطلاع‌رسانی: تحویل عادی تکمیل اجرای فرزند همچنان در اختیار اعلان‌های زیرعامل است و گزارش سیگنال‌ها هرگز آن را تکرار نمی‌کند.

ناظران

ناظر نشستی است که یک مکان‌نما (session_watch_cursors) روی هدف نگه می‌دارد. مکان‌نماها از دو محل ایجاد می‌شوند:

• ضمنی (یال‌های ایجاد). وقتی یک نشست زیرعامل یا فرزند ACP ایجاد می‌کند، مکان‌نمای والد به‌طور خودکار روی نسخه زمان ایجاد فرزند مقداردهی اولیه می‌شود. والدها هرگز به‌صورت دستی مشترک نمی‌شوند.
• صریح (sessions_send watch: true). هر هماهنگ‌کننده‌ای می‌تواند هدفی را که خود ایجاد نکرده است نظارت کند: در sessions_send مقدار watch: true را ارسال کنید؛ پس از ارسال موفق پیام، فرستنده به‌عنوان ناظر نشستی ثبت می‌شود که واقعاً پیام را دریافت کرده است. ثبت از نسخه وضعیت فعلی هدف آغاز می‌شود — تاریخچه پیشین هرگز اعلان ایجاد نمی‌کند. وقتی پارامتر تنظیم شده باشد، نتیجه ابزار watched: true|false را گزارش می‌کند.

هویت ناظر باید یک کلید نشست واجد شناسه عامل باشد. در session.scope="global"، کلید مشترک global میان عامل‌ها مبهم است؛ بنابراین چنین نشست‌هایی گزارش پایدار و changesSince را دریافت می‌کنند، اما اعلان پیش‌دستانه‌ای نمی‌گیرند.

نظارت‌ها خودکار پاک‌سازی می‌شوند: ردیف‌های مکان‌نما هم‌زمان با دوره نگهداری گزارش سیگنال منقضی می‌شوند، هنگام بازنشانی نشست ناظر حذف می‌شوند و با حذف هر یک از دو نشست نیز پاک می‌شوند. در v1 فعلی برای لغو نظارت وجود ندارد.

نشست‌های تحت نظارتی که از فهرست نشست‌ها پذیرفته شده‌اند، با تناوبی ثابت از نظر فعالیت مستقیم انسان در منبع بالادستی بررسی می‌شوند. فعالیت شناسایی‌شده مانند دیگر نوبت‌های مستقیم انسانی وارد همان گزارش سیگنال و جریان ناظران می‌شود.

اگر منبع بالادستی یک نشست پذیرفته‌شده به‌صورت خارجی حذف شود، سه بررسی ناموفق متوالی (حدود سه تیک پایش) یک سیگنال upstream_missing برای ناظران آن ایجاد می‌کند و پیوند بالادستی را حذف می‌کند. ادامه دوباره نشست فهرست، پیوند تازه‌ای ایجاد می‌کند.

اعلان‌ها: یکی، نه چندتا

وقتی رویدادی واجد شرایط اطلاع‌رسانی ثبت شود و مکان‌نمای ناظر عقب‌تر باشد، ناظر در نوبت بعدی خود یک اعلان سیستمی دریافت می‌کند:

نشست "agent:main:subagent:child" تغییر کرد (بازیگر دیگر). پیش از اقدام همگام‌سازی مجدد کنید: session_status sessionKey "agent:main:subagent:child" changesSince 12.

ناظران نشست اصلی نیز بلافاصله با یک بیدارباش Heartbeat فعال می‌شوند؛ ناظران زیرعامل تو‌در‌تو اعلان را در نوبت بعدی خود دریافت می‌کنند.

پروتکل عمداً ضد هرزآگهی است:

• یک اعلان در انتظار برای هر جفت ناظر/هدف. متن اعلان تا زمانی که در انتظار است از نظر بایتی ثابت می‌ماند و صف رویداد سیستمی آن را تکرارزدایی می‌کند؛ بنابراین حتی بیست تغییر سریع در یک هدف نیز فقط یک خط در اعلان ناظر ایجاد می‌کند.
• نقطه اوج ثابت. وقتی اعلان در صف قرار می‌گیرد، مکان‌نما موقعیت اطلاع‌داده‌شده خود را ثابت نگه می‌دارد. رویدادهای معنادار بعدی فقط نقطه اوج معنادار را جلو می‌برند؛ آن‌ها دوباره اعلان نمی‌کنند.
• تأیید هنگام تخلیه، بازگشایی فقط برای کارهای میان‌لایه‌ای. وقتی نوبت ناظر اعلان را مصرف می‌کند، مکان‌نما جلو می‌رود. اگر میان صف‌شدن و تخلیه، رویدادهای معنادار بیشتری رسیده باشند، دقیقاً یک اعلان تازه برای باقی‌مانده باز می‌شود.
• سرکوب خودی. ناظر هرگز درباره رویدادهایی که خودش ایجاد کرده است مطلع نمی‌شود.
• بازیابی پس از راه‌اندازی مجدد. اعلان‌های در انتظار در یک صف درون‌حافظه‌ای قرار دارند؛ پس از راه‌اندازی مجدد Gateway، یک پیمایش آغازین آن‌ها را از مکان‌نماهای پایدار دوباره ایجاد می‌کند.

همگام‌سازی مجدد

اعلان دقیقاً به ناظر می‌گوید چه کاری انجام دهد. session_status با changesSince: <version> رویدادهای نوع‌دار پس از آن نسخه را (حداکثر 200 مورد) بدون جلو بردن هیچ مکان‌نمایی برمی‌گرداند:

{  "stateVersion": 19,  "stateChanges": {    "events": [      {        "sequence": 14,        "kind": "human_direct_message",        "actorType": "human",        "summary": "پیام انسانی از طریق telegram"      },      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "هدف به‌روزرسانی شد" }    ],    "historyGap": false  }}

historyGap: true یعنی نسخه درخواستی قدیمی‌تر از تاریخچه نگهداری‌شده است — به‌جای درنظرگرفتن پاسخ به‌عنوان اختلاف دقیق، کل وضعیت نشست (sessions_history، session_status) را تازه‌سازی کنید. سیگنال شکاف دقیق است: این سیگنال از یک نقطه اوج هرس‌شده مختص نشست می‌آید و از محاسبات توالی استنتاج نمی‌شود.

ذخیره‌سازی و محدودیت‌ها

تاریخچه در پایگاه داده وضعیت مشترک نگهداری می‌شود و به 30 روز و 50,000 ردیف محدود است؛ سرآیندهای مختص نشست پس از هرس نیز یکنواخت صعودی باقی می‌مانند. ثبت به‌صورت بهترین‌تلاش انجام می‌شود — افزودن ناموفق ثبت می‌شود و هرگز نوبت مبدأ را با شکست مواجه نمی‌کند — بنابراین stateVersion یک سرآیند گزارش سیگنال است، نه نسخه ثبت تغییرات داده‌ای تراکنشی.

محدودیت‌های فعلی:

• تحویل اعلان فرض می‌کند یک فرایند Gateway مالک پایگاه داده وضعیت مشترک است. چند Gateway گزارش پایدار و changesSince را به اشتراک می‌گذارند، اما v1 اعلان‌ها را میان فرایندها ارسال نمی‌کند.
• رویدادهای Compaction مالکان Compaction زمان‌اجرای توکار را پوشش می‌دهند؛ Compaction مختص مهار بومی به‌طور کامل ثبت نمی‌شود.
• جزئیات داده نتیجه لغوشده در حال حاضر توسط اجراهای فرزند ACP تولید می‌شود؛ لغوهای زیرعامل بومی به‌صورت شکست‌های عمومی نمایش داده می‌شوند.
• تشخیص بازتاب خودی بالادستی، متن عادی‌سازی‌شده کاربر را مقایسه می‌کند. پرامپت خارجی که با یکی از 10 پیام اخیر کاربر در سمت OpenClaw نشست مطابقت داشته باشد، بازتاب خودی در نظر گرفته می‌شود.
• یک ردیف محلی Claude JSONL بزرگ‌تر از سقف پیمایش 1 MiB در هر تناوب، مکان‌نمای آن نشست را در v1 مسدود می‌کند؛ بایت‌های طبقه‌بندی‌نشده هرگز نادیده گرفته نمی‌شوند.
• بررسی‌های Claude در Node جفت‌شده، آخرین 50 مورد رونوشت را در هر تناوب طبقه‌بندی می‌کنند. جهش‌های بزرگ‌تر ممکن است خارج از پنجره پیمایش v1 قرار بگیرند.
• خواندن تاریخچه Claude در Node جفت‌شده نتیجه قطعی برای پیدانشدن رشته گفتگو ارائه نمی‌کند؛ بنابراین حذف‌های راه‌دور Claude در v1 به‌عنوان upstream_missing طبقه‌بندی نمی‌شوند.
• نشست‌های فهرستی که پذیرفته نشده‌اند، در v1 خارج از لایه آگاهی باقی می‌مانند.
• نشست‌هایی که پیش از این قابلیت پذیرفته شده‌اند، هیچ پیوند بالادستی ندارند؛ یک‌بار آن‌ها را از فهرست ادامه دهید تا پایش بالادستی آغاز شود.
• پیوندهای بالادستی فرض می‌کنند هر کلید نشست پذیرفته‌شده به یک عامل مالک نگاشت می‌شود (پذیرش از عامل پیش‌فرض مخزن استفاده می‌کند). پذیرش چندعاملی یک رشته خارجی یکسان در v1 پایش نمی‌شود.

مرتبط

• ابزارهای نشست — sessions_send، session_status، sessions_list
• زیرعامل‌ها — یال‌های ایجاد و اعلان‌های تکمیل
• Heartbeat — نحوه بیدارکردن نشست‌های اصلی توسط اعلان‌های صف‌شده
• مدیریت نشست — کلیدها، دامنه‌ها و چرخه عمر نشست