Co-authored-by: Chaim Marcus <chaim@marcus-law.co.il> Co-committed-by: Chaim Marcus <chaim@marcus-law.co.il>
261 lines
11 KiB
TypeScript
261 lines
11 KiB
TypeScript
/**
|
||
* הפשטת 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<string, unknown>): void },
|
||
fn: () => Promise<void>,
|
||
): Promise<void> {
|
||
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<Record<string, unknown> | null>;
|
||
/** עוטף `ctx.state.get` ב-scope `instance` על `LEGAL_API_BASE_CACHE_KEY`. */
|
||
readCache(): Promise<unknown>;
|
||
/** עוטף `ctx.state.set` ב-scope `instance` על `LEGAL_API_BASE_CACHE_KEY`. */
|
||
writeCache(url: string): Promise<void>;
|
||
/** מזהי כל החברות המוכרות לפלאגין (`Object.keys(CEO_AGENT_IDS)`). */
|
||
knownCompanyIds: readonly string[];
|
||
/** ברירת-המחדל כש-legal-ai לא הוגדר בכלל (אינסטנס לא-מוגדר, לא scope שנדחה). */
|
||
defaultBaseUrl: string;
|
||
logger: {
|
||
info(message: string, meta?: Record<string, unknown>): void;
|
||
warn(message: string, meta?: Record<string, unknown>): 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<string> {
|
||
const {
|
||
readConfig,
|
||
readCache,
|
||
writeCache,
|
||
knownCompanyIds,
|
||
defaultBaseUrl,
|
||
logger,
|
||
companyId,
|
||
} = deps;
|
||
|
||
let sawScopeDenied = false;
|
||
|
||
// כותב ל-cache רק כשהערך השתנה בפועל — ראה `lastWrittenApiBase` למעלה.
|
||
const writeCacheIfChanged = async (url: string): Promise<void> => {
|
||
if (url === lastWrittenApiBase) return;
|
||
await writeCache(url);
|
||
lastWrittenApiBase = url;
|
||
};
|
||
|
||
const tryRead = async (id?: string): Promise<string | null | undefined> => {
|
||
let cfg: Record<string, unknown> | 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;
|
||
}
|