/** * הפשטת company-scope לג'ובים מתוזמנים ול-webhook (legal-ai issue #637). * * המקור לבאג: מאז @paperclipai/server 2026.722.0 אין scope של חברה * ל-`runJob`/`handleWebhook` — המארח מדפיס scope רק מ-`params.companyId` / * `performAction.actorContext` / `executeTool.runContext` / * `onEvent.event.companyId` (plugin-worker-manager.js:191-210), ו- * `plugin-job-scheduler.js:184` שולח `runJob` בלי `companyId` כלל. לכן כל * קריאה מתוך ג'וב ל-`ctx.config.get`/`ctx.issues.*`/`ctx.agents.invoke`/ * `ctx.events.emit` נדחית ע"י המארח עם `InvocationScopeDeniedError` * (host-client-factory.js:253-293) — קוד `-32005`. * * המודול הזה טהור בכוונה — כמו `sync-target.ts` — כדי שאפשר יהיה לייבא * אותו בטסט בלי להריץ את `runWorker(plugin, import.meta.url)` שקורה בזמן * import של worker.ts. הייבוא היחיד מה-SDK הוא ייבוא-ערך של * `PLUGIN_RPC_ERROR_CODES` — קבוע פרוטוקול נטול side-effects, לא ה-runtime * של הפלאגין עצמו. */ import { PLUGIN_RPC_ERROR_CODES } from "@paperclipai/plugin-sdk"; /** מפתח ה-`ctx.state` (scope `instance`) שבו נשמר ה-base URL האחרון שהצלחנו לפתור. */ export const LEGAL_API_BASE_CACHE_KEY = "legal-api-base-url"; /** * זיכרון-תהליך (לא `ctx.state`) של ה-base URL האחרון שבאמת נכתב ל-cache. * `LegalApi.request` (`legal-api.ts:19-32`) קורא ל-`resolveBaseUrl()` — * וכך ל-`resolveApiBaseFrom` — בכל בקשת-API בודדת, אבל הערך כמעט לעולם * לא משתנה; בלי המנגנון הזה כל קריאת-כלי/`usePluginData` הייתה מוסיפה * `ctx.state.set` (=upsert ל-Postgres) מיותר. */ let lastWrittenApiBase: string | undefined; /** מאפס את זיכרון-המטמון ברמת-המודול. **לשימוש טסטים בלבד.** */ export function _resetApiBaseCacheMemo(): void { lastWrittenApiBase = undefined; } /** * האם השגיאה היא דחיית-scope של המארח (קוד `-32005`, * `PLUGIN_RPC_ERROR_CODES.INVOCATION_SCOPE_DENIED`). זיהוי **מבני** לפי * שדה `code` — לא התאמת-מחרוזת על `err.message`, שיכולה להישבר בשקט אם * המארח ינסח את ההודעה מחדש. */ export function isCompanyScopeDenied(err: unknown): boolean { return ( typeof err === "object" && err !== null && "code" in err && (err as { code?: unknown }).code === PLUGIN_RPC_ERROR_CODES.INVOCATION_SCOPE_DENIED ); } /** * מחלץ טקסט קריא מ-`cause` שגוי-scope. המארח שולח `JsonRpcCallError` * (מופע `Error` עם `.message` תיאורי מהצד השני), אבל בטסטים/עתידית ייתכן * גם אובייקט-שגיאה פשוט בלי prototype chain — לכן בדיקה מבנית ולא רק * `instanceof Error`. */ function describeCause(cause: unknown): string { if (cause instanceof Error) return cause.message; if ( typeof cause === "object" && cause !== null && "message" in cause && typeof (cause as { message?: unknown }).message === "string" ) { return (cause as { message: string }).message; } return String(cause); } /** * נזרקת כש-handler של ג'וב/webhook נתקל בדחיית-scope שאין לו דרך לעקוף * אותה. ההודעה עצמה היא האבחנה — היא מה שיישמר ב-`plugin_job_runs.error` * (או `plugin_webhook_deliveries.error`), ו-`plugin_logs` ריק לחלוטין * (נמדד), כך שזו למעשה עדות-הכשל היחידה שתישאר. **חובה** להעביר `cause` * כשהוא ידוע — המתזמר של Paperclip (`plugin-job-scheduler.js:199`) רושם * ל-DB רק את `err.message`, ואינו מטייל ב-`Error.cause`, כך שכל מידע * שלא נכנס למחרוזת-ההודעה עצמה אובד. */ export class CompanyScopeUnavailableError extends Error { readonly jobKey: string; readonly method: string; constructor(jobKey: string, method: string, options?: { cause?: unknown }) { // method="unknown" קורה כש-runJobHandler תופס דחיית-scope בלי לדעת // איזו קריאה נדחתה בפועל (ה-handler לא ציין method מפורש). לא לכתוב // את המילה "unknown" להודעה — במקום זה מסתמכים על ה-cause בלבד. const methodClause = method === "unknown" ? "" : ` הפעולה שנדחתה: "${method}".`; const sourceClause = options?.cause !== undefined ? ` מקור: ${describeCause(options.cause)}.` : ""; super( `${jobKey}: נדרש הקשר-חברה (company scope) לפעולה זו, אבל ג'וב ` + "מתוזמן/webhook אינו מקבל כזה מ-Paperclip (מאז server " + `2026.722.0).${methodClause}${sourceClause} ראה legal-ai issue #637.`, options, ); this.name = "CompanyScopeUnavailableError"; this.jobKey = jobKey; this.method = method; } } /** * מריץ handler של ג'וב, ובכשל — מלוגג **וזורק מחדש**. המתזמר של Paperclip * (`plugin-job-scheduler.js:194-215`) כבר רושם `status:"failed"` כש-RPC * נדחה; מה שהיה שבור זה ה-handlers שלנו, שבלעו את השגיאה ב- * `catch (err) { ctx.logger.error(...) }` בלי `throw` — כך ה-RPC נפתר * בהצלחה וה-run נרשם `succeeded` למרות שלא עשה כלום (13,928 ריצות כוזבות, * נמדד). ה-README של ה-SDK: "Re-throw from the handler to mark the run as * failed". * * דחיית-scope הופכת ל-`CompanyScopeUnavailableError` מאבחנת; כל שגיאה * אחרת נזרקת כמות-שהיא. */ export async function runJobHandler( jobKey: string, logger: { error(message: string, meta?: Record): void }, fn: () => Promise, ): Promise { try { await fn(); } catch (err) { logger.error(`${jobKey}: job failed`, { error: String(err) }); if (isCompanyScopeDenied(err)) { throw new CompanyScopeUnavailableError(jobKey, "unknown", { cause: err, }); } throw err; } } /** תלויות מוזרקות לפתירת `legalApiBaseUrl` — כדי שהלוגיקה תהיה בת-טסט בלי `ctx` אמיתי. */ export interface ResolveApiBaseDeps { /** עוטף `ctx.config.get(companyId)`. **לא** בולע — זורק כשהמארח דוחה scope. */ readConfig(companyId?: string): Promise | null>; /** עוטף `ctx.state.get` ב-scope `instance` על `LEGAL_API_BASE_CACHE_KEY`. */ readCache(): Promise; /** עוטף `ctx.state.set` ב-scope `instance` על `LEGAL_API_BASE_CACHE_KEY`. */ writeCache(url: string): Promise; /** מזהי כל החברות המוכרות לפלאגין (`Object.keys(CEO_AGENT_IDS)`). */ knownCompanyIds: readonly string[]; /** ברירת-המחדל כש-legal-ai לא הוגדר בכלל (אינסטנס לא-מוגדר, לא scope שנדחה). */ defaultBaseUrl: string; logger: { info(message: string, meta?: Record): void; warn(message: string, meta?: Record): void; }; /** ידוע רק כשהמארח מספק אחד (handler בהקשר-חברה) — אופציונלי. */ companyId?: string; } /** * פותר `legalApiBaseUrl` מ-config בהיקף-חברה, עם נפילה-חזרה למטמון * (`ctx.state`, scope `instance`) כשאין כלל הקשר-חברה זמין (ג'וב/webhook). * * ⚠️ כשכל ניסיונות ה-`readConfig` נדחים ב-scope **ואין** מטמון — זורקים * `CompanyScopeUnavailableError`. **אסור** להחזיר `defaultBaseUrl` במקרה * הזה: זה בדיוק מה שיצר את `TypeError: fetch failed` המטעה — `worker.ts` * הישן בלע את דחיית-ה-scope כ"אין קונפיג" ונפל ל- * `http://localhost:8085` שאין בו מאזין. */ export async function resolveApiBaseFrom( deps: ResolveApiBaseDeps, ): Promise { const { readConfig, readCache, writeCache, knownCompanyIds, defaultBaseUrl, logger, companyId, } = deps; let sawScopeDenied = false; // כותב ל-cache רק כשהערך השתנה בפועל — ראה `lastWrittenApiBase` למעלה. const writeCacheIfChanged = async (url: string): Promise => { if (url === lastWrittenApiBase) return; await writeCache(url); lastWrittenApiBase = url; }; const tryRead = async (id?: string): Promise => { let cfg: Record | null; try { cfg = await readConfig(id); } catch (err) { if (isCompanyScopeDenied(err)) { sawScopeDenied = true; return undefined; // נדחה — נסה את המקור הבא } // שגיאה אחרת: אין בליעה שקטה — מדווחים וממשיכים לנסות את הבא. logger.warn("resolveApiBase: config.get failed", { companyId: id ?? null, error: String(err), }); return undefined; } const url = cfg?.legalApiBaseUrl; return typeof url === "string" && url.trim() ? url.trim() : null; }; if (companyId) { const scoped = await tryRead(companyId); if (scoped) { await writeCacheIfChanged(scoped); return scoped; } } // אין companyId ישיר (או שהקריאה מולו נדחתה) — אבל המארח מסיק בעצמו // companyId כשהקריאה מתרחשת בתוך הקשר host-scoped (למשל tool handler). // לנסות לפני נפילה-לניחוש. נשאר בהתנהגות המקורית: מנוסה תמיד, לא רק // כשלא סופק companyId. const derived = await tryRead(undefined); if (derived) { await writeCacheIfChanged(derived); return derived; } // ג'וב מתוזמן/webhook ללא הקשר-חברה כלל: לנסות כל חברה מוכרת. בפועל // כולן מצביעות על אותו מופע legal-ai, כך שהפגיעה הראשונה מנצחת. for (const knownCompanyId of knownCompanyIds) { const url = await tryRead(knownCompanyId); if (url) { await writeCacheIfChanged(url); return url; } } if (sawScopeDenied) { // כל הניסיונות נדחו ב-scope (לא "לא-מוגדר") — לנסות את המטמון לפני // שנכשל. מצב-צפוי בג'וב, ולכן `info` ולא `warn`. const cached = await readCache(); if (typeof cached === "string" && cached.trim()) { logger.info( "resolveApiBase: config.get denied (no company scope) — using cached legalApiBaseUrl", { cachedBaseUrl: cached }, ); return cached; } throw new CompanyScopeUnavailableError("resolveApiBase", "config.get"); } // כל הקריאות הצליחו (לא נדחו) אך אף אחת לא החזירה ערך — legal-ai פשוט // לא הוגדר עדיין. זה מצב שונה מהותית מדחיית-scope: מותר ליפול לברירת-מחדל. logger.warn("legalApiBaseUrl unresolved — using default", { companyId: companyId ?? null, fallback: defaultBaseUrl, }); return defaultBaseUrl; }