Gateway

Gateway هو مستوى التحكم المركزي لـ Triggerfish -- خدمة محلية طويلة التشغيل تنسق الجلسات والقنوات والأدوات والأحداث وعمليات الوكيل من خلال نقطة نهاية WebSocket واحدة. كل ما يحدث في Triggerfish يتدفق عبر Gateway.

البنية

يستمع Gateway على منفذ قابل للتكوين (افتراضي 18789) ويقبل الاتصالات من محولات القنوات، وأوامر CLI، والتطبيقات المرافقة، والخدمات الداخلية. جميع الاتصالات تستخدم JSON-RPC عبر WebSocket.

خدمات Gateway

يوفر Gateway هذه الخدمات من خلال نقاط نهاية WebSocket و HTTP:

الخدمة	الوصف	تكامل الأمان
الجلسات	إنشاء، سرد، استرجاع السجل، إرسال بين الجلسات، إنشاء مهام خلفية	تتبع taint الجلسة لكل جلسة
القنوات	توجيه الرسائل، إدارة الاتصالات، إعادة محاولة التسليم الفاشل، تقسيم الرسائل الكبيرة	فحوصات تصنيف على كل مخرج
Cron	جدولة المهام المتكررة وإيقاظ triggers من TRIGGER.md	إجراءات cron تمر عبر hooks السياسات
Webhooks	قبول الأحداث الواردة من خدمات خارجية عبر POST /webhooks/:sourceId	تُصنف البيانات الواردة عند الاستيعاب
Ripple	تتبع حالة الاتصال ومؤشرات الكتابة عبر القنوات	لا تُكشف بيانات حساسة
التكوين	إعادة تحميل الإعدادات ساخنة بدون إعادة تشغيل	المسؤول فقط في المؤسسات
واجهة التحكم	لوحة ويب لصحة gateway وإدارته	مُصادق عليها بالرمز
Tide Pool	استضافة مساحة عمل A2UI المرئية المدفوعة بالوكيل	المحتوى يخضع لـ hooks المخرجات
الإشعارات	تسليم إشعارات عبر القنوات مع توجيه بالأولوية	تنطبق قواعد التصنيف

بروتوكول WebSocket JSON-RPC

يتصل العملاء بـ Gateway عبر WebSocket ويتبادلون رسائل JSON-RPC 2.0. كل رسالة هي استدعاء طريقة بمعاملات مُنمطة واستجابة مُنمطة.

// يُرسل العميل:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sessions.list",
  "params": { "filter": "active" }
}

// يستجيب Gateway:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    { "id": "sess_abc", "taint": "CONFIDENTIAL", "channel": "telegram" },
    { "id": "sess_def", "taint": "PUBLIC", "channel": "cli" }
  ]
}

يخدم Gateway أيضاً نقاط نهاية HTTP لاستيعاب webhook. عند إرفاق SchedulerService، تتوفر مسارات POST /webhooks/:sourceId لأحداث webhook الواردة.

واجهة الخادم

interface GatewayServerOptions {
  /** المنفذ للاستماع عليه. استخدم 0 لمنفذ عشوائي متاح. */
  readonly port?: number;
  /** رمز المصادقة للاتصالات. */
  readonly authToken?: string;
  /** خدمة جدولة اختيارية لنقاط نهاية webhook. */
  readonly schedulerService?: SchedulerService;
}

interface GatewayAddr {
  readonly port: number;
  readonly hostname: string;
}

interface GatewayServer {
  /** بدء الخادم. يُعيد العنوان المُرتبط. */
  start(): Promise<GatewayAddr>;
  /** إيقاف الخادم بشكل رشيق. */
  stop(): Promise<void>;
}

المصادقة

اتصالات Gateway مُصادقة بالرمز. يُنشأ الرمز أثناء الإعداد (triggerfish dive) ويُخزن محلياً.

SECURITY يرتبط Gateway بـ 127.0.0.1 افتراضياً وليس مكشوفاً على

الشبكة. يتطلب الوصول عن بُعد تكوين نفق صريح. لا تكشف أبداً WebSocket الخاص بـ Gateway على الإنترنت العام بدون مصادقة. :::

إدارة الجلسات

يدير Gateway دورة حياة الجلسات الكاملة. الجلسات هي الوحدة الأساسية لحالة المحادثة، كل منها مع تتبع taint مستقل.

أنواع الجلسات

النوع	نمط المفتاح	الوصف
رئيسي	main	المحادثة المباشرة الرئيسية مع المالك. تستمر عبر إعادات التشغيل.
قناة	channel:<type>:<id>	واحدة لكل قناة متصلة. taint معزول لكل قناة.
خلفية	bg:<task_id>	تُنشأ لمهام cron ومهام webhook. تبدأ بـ taint PUBLIC.
وكيل	agent:<agent_id>	جلسات لكل وكيل للتوجيه متعدد الوكلاء.
مجموعة	group:<channel>:<group_id>	جلسات محادثة جماعية.

أدوات الجلسات

يتفاعل الوكيل مع الجلسات عبر هذه الأدوات، جميعها موجهة عبر Gateway:

الأداة	الوصف	تأثيرات Taint
sessions_list	سرد الجلسات النشطة مع مرشحات اختيارية	لا تغيير في taint
sessions_history	استرجاع نص الجلسة	Taint يرث من الجلسة المُشار إليها
sessions_send	إرسال رسالة إلى جلسة أخرى	يخضع لفحص منع الكتابة للأسفل
sessions_spawn	إنشاء جلسة مهمة خلفية	الجلسة الجديدة تبدأ بـ taint PUBLIC
session_status	فحص حالة الجلسة الحالية والنموذج والتكلفة	لا تغيير في taint

الاتصال بين الجلسات عبر sessions_send يخضع لنفس قواعد منع الكتابة

للأسفل كأي مخرج آخر. لا يمكن لجلسة CONFIDENTIAL إرسال بيانات إلى جلسة متصلة بقناة PUBLIC. :::

توجيه القنوات

يوجه Gateway الرسائل بين القنوات والجلسات عبر موجه القنوات. يتعامل الموجه مع:

• بوابة التصنيف: كل رسالة صادرة تمر عبر PRE_OUTPUT قبل التسليم
• إعادة المحاولة مع تراجع: يُعاد محاولة التسليم الفاشل بتراجع أُسّي عبر sendWithRetry()
• تقسيم الرسائل: تُقسم الرسائل الكبيرة إلى أجزاء مناسبة للمنصة (مثل حد Telegram البالغ 4096 حرفاً)
• البث: تُبث الاستجابات للقنوات التي تدعمه
• إدارة الاتصال: connectAll() و disconnectAll() لإدارة دورة الحياة

خدمة الإشعارات

يدمج Gateway خدمة إشعارات من الدرجة الأولى تحل محل أنماط "إخطار المالك" المؤقتة عبر المنصة. جميع الإشعارات تتدفق عبر NotificationService واحد.

interface NotificationService {
  notify(recipient: UserId, notification: Notification): Promise<void>;
  getPreferences(userId: UserId): Promise<NotificationPreference>;
  setPreferences(userId: UserId, prefs: NotificationPreference): Promise<void>;
  getPending(userId: UserId): Promise<Notification[]>;
}

توجيه الأولوية

الأولوية	السلوك
CRITICAL	تجاوز ساعات الهدوء، التسليم لجميع القنوات المتصلة فوراً
HIGH	التسليم للقناة المفضلة فوراً، ترتيب في قائمة الانتظار إذا غير متصل
NORMAL	التسليم للجلسة النشطة، أو ترتيب لبدء الجلسة التالية
LOW	ترتيب، التسليم على دفعات أثناء الجلسات النشطة

مصادر الإشعارات

المصدر	الفئة	الأولوية الافتراضية
انتهاكات السياسات	security	CRITICAL
تنبيهات استخبارات التهديد	security	CRITICAL
طلبات الموافقة على المهارات	approval	HIGH
فشل مهام cron	system	HIGH
تحذيرات صحة النظام	system	HIGH
أحداث webhook	info	NORMAL
تحديثات The Reef المتاحة	info	LOW

تُخزن الإشعارات عبر StorageProvider (مساحة الاسم: notifications:) وتنجو من إعادات التشغيل. الإشعارات غير المُسلمة يُعاد محاولتها عند بدء Gateway التالي أو اتصال الجلسة.

تفضيلات التسليم

يُكوّن المستخدمون تفضيلات الإشعارات لكل قناة:

notifications:
  preferred_channel: telegram
  quiet_hours:
    start: "22:00"
    end: "07:00"
    timezone: "America/Chicago"
  overrides:
    security: all_channels
    approval: preferred_channel
    info: active_session

تكامل المجدول

يستضيف Gateway خدمة المجدول، التي تدير:

• حلقة tick لـ cron: تقييم دوري للمهام المجدولة
• إيقاظ triggers: إيقاظ الوكيل المُعرّف في TRIGGER.md
• نقاط نهاية HTTP لـ webhook: POST /webhooks/:sourceId للأحداث الواردة
• عزل المنسق: كل مهمة مجدولة تعمل في OrchestratorFactory خاص بها مع حالة جلسة معزولة

المهام المُشغلة بـ cron و webhook تُنشئ جلسات خلفية بـ taint PUBLIC

جديد. لا ترث taint أي جلسة موجودة، مما يضمن أن المهام المستقلة تبدأ بحالة تصنيف نظيفة. :::

الصحة والتشخيص

يتصل أمر triggerfish patrol بـ Gateway ويُجري فحوصات صحة تشخيصية، ويتحقق من:

• Gateway يعمل ويستجيب
• جميع القنوات المُكوّنة متصلة
• التخزين يمكن الوصول إليه
• المهام المجدولة تُنفذ في الوقت المحدد
• لا توجد إشعارات حرجة غير مُسلمة عالقة في قائمة الانتظار