Gateway

ה-Gateway הוא מישור הבקרה המרכזי של Triggerfish -- שירות מקומי שרץ לאורך זמן ומתאם סשנים, ערוצים, כלים, אירועים ותהליכי סוכן דרך נקודת קצה WebSocket יחידה. כל מה שקורה ב-Triggerfish זורם דרך ה-Gateway.

ארכיטקטורה

ה-Gateway מאזין על פורט ניתן להגדרה (ברירת מחדל 18789) ומקבל חיבורים ממתאמי ערוצים, פקודות CLI, אפליקציות Buoy ושירותים פנימיים. כל התקשורת משתמשת ב-JSON-RPC על גבי WebSocket.

שירותי Gateway

ה-Gateway מספק את השירותים הבאים דרך נקודות הקצה שלו ב-WebSocket ו-HTTP:

שירות	תיאור	אינטגרציית אבטחה
סשנים	יצירה, רישום, אחזור היסטוריה, שליחה בין סשנים, יצירת משימות רקע	מעקב Taint של סשן לכל סשן
ערוצים	ניתוב הודעות, ניהול חיבורים, ניסיון חוזר למשלוחים כושלים, חלוקת הודעות גדולות	בדיקות סיווג על כל הפלט
Cron	תזמון משימות חוזרות והתעוררויות טריגר מ-TRIGGER.md	פעולות Cron עוברות דרך Hook-י מדיניות
Webhooks	קבלת אירועים נכנסים משירותים חיצוניים דרך POST /webhooks/:sourceId	נתונים נכנסים מסווגים בעת קליטה
Ripple	מעקב אחר סטטוס מקוון ומחוני הקלדה בין ערוצים	ללא חשיפת נתונים רגישים
הגדרות	טעינה מחדש של הגדרות ללא הפעלה מחדש	מנהל בלבד בסביבה ארגונית
ממשק בקרה	לוח מחוונים לבריאות וניהול Gateway	מאומת בטוקן
Tide Pool	אירוח סביבת עבודה חזותית A2UI מונעת סוכן	תוכן כפוף ל-Hook-י פלט
התראות	משלוח התראות רב-ערוצי עם ניתוב לפי עדיפות	כללי סיווג חלים

פרוטוקול 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) ומאוחסן מקומית.

אבטחה ה-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()
• חלוקת הודעות: הודעות גדולות מחולקות לחלקים מותאמים לפלטפורמה (למשל, מגבלת 4096 תווים של Telegram)
• הזרמה: תגובות מוזרמות לערוצים התומכים בכך
• ניהול חיבורים: 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
בקשות אישור Skills	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: הערכה תקופתית של משימות מתוזמנות
• התעוררויות טריגר: התעוררויות סוכן המוגדרות ב-TRIGGER.md
• נקודות קצה HTTP ל-Webhook: POST /webhooks/:sourceId לאירועים נכנסים
• בידוד Orchestrator: כל משימה מתוזמנת רצה ב-OrchestratorFactory משלה עם מצב סשן מבודד

משימות שהופעלו על ידי Cron ו-Webhook יוצרות סשני רקע עם Taint PUBLIC

טרי. הן לא יורשות את ה-Taint של סשן קיים כלשהו, מה שמבטיח שמשימות אוטונומיות מתחילות עם מצב סיווג נקי. :::

בריאות ואבחון

הפקודה triggerfish patrol מתחברת ל-Gateway ומריצה בדיקות אבחון בריאות, ומאמתת:

• ה-Gateway רץ ומגיב
• כל הערוצים המוגדרים מחוברים
• האחסון נגיש
• משימות מתוזמנות מתבצעות בזמן
• אין התראות קריטיות שלא נמסרו תקועות בתור