@easyoref/agent 1.21.1

package/src/tools/alert-history.ts

@@ -0,0 +1,120 @@
+/**
+ * Alert history tool — query Pikud HaOref history.
+ */
+
+/** Format date as DD.MM.YYYY for Oref history API */
+function formatOrefDate(d: Date): string {
+  const dd = String(d.getDate()).padStart(2, "0");
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const yyyy = d.getFullYear();
+  return `${dd}.${mm}.${yyyy}`;
+}
+
+export { formatOrefDate };
+
+import * as logger from "@easyoref/monitoring";
+import { config } from "@easyoref/shared";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+export const alertHistoryTool = tool(
+  async ({
+    area,
+    lastMinutes,
+  }: {
+    area: string;
+    lastMinutes: number;
+  }): Promise<string> => {
+    try {
+      const historyUrl =
+        config.orefHistoryUrl ??
+        "https://www.oref.org.il/Shared/Ajax/GetAlarmsHistory.aspx?lang=he&fromDate=" +
+          formatOrefDate(new Date(Date.now() - lastMinutes * 60_000)) +
+          "&toDate=" +
+          formatOrefDate(new Date());
+
+      const res = await fetch(historyUrl, {
+        headers: {
+          "User-Agent":
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
+          "X-Requested-With": "XMLHttpRequest",
+          Referer: "https://www.oref.org.il/",
+          Accept: "application/json, text/plain, */*",
+        },
+        signal: AbortSignal.timeout(5000),
+      });
+
+      if (!res.ok) {
+        return JSON.stringify({
+          error: `Oref history API returned ${res.status}`,
+          retry: true,
+        });
+      }
+
+      const text = await res.text();
+      if (!text.trim()) {
+        return JSON.stringify({
+          area,
+          alerts: [],
+          note: "No alert history returned for this period",
+        });
+      }
+
+      const parsed: unknown = JSON.parse(text);
+      const alerts = Array.isArray(parsed) ? parsed : [parsed];
+
+      const relevant = alerts.filter((a: Record<string, unknown>) => {
+        const data = (a.data as string) ?? "";
+        return data.includes(area) || area.includes(data.split(" ")[0] ?? "");
+      });
+
+      const result = {
+        area,
+        last_minutes: lastMinutes,
+        alerts: relevant.slice(0, 20).map((a: Record<string, unknown>) => ({
+          date: a.alertDate ?? a.date,
+          title: a.title,
+          data: a.data,
+          category: a.category_desc ?? a.category,
+        })),
+        total_in_period: alerts.length,
+        relevant_count: relevant.length,
+        queried_at: new Date().toISOString(),
+      };
+
+      logger.info("Tool: alert_history executed", {
+        area,
+        last_minutes: lastMinutes,
+        total: alerts.length,
+        relevant: relevant.length,
+      });
+
+      return JSON.stringify(result);
+    } catch (err) {
+      logger.warn("Tool: alert_history failed", { error: String(err) });
+      return JSON.stringify({
+        error: `Oref history API call failed: ${String(err)}`,
+        retry: true,
+      });
+    }
+  },
+  {
+    name: "alert_history",
+    description:
+      "Get recent alert history from Pikud HaOref (Israel Home Front Command). " +
+      "Answers: 'was there really an alert in area X in the last N minutes?' " +
+      "More useful than active alerts (the bot already has the current alert). " +
+      "Use to verify channel claims about attacks in specific areas.",
+    schema: z.object({
+      area: z
+        .string()
+        .describe("Hebrew area name to search for in history (e.g. תל אביב)"),
+      lastMinutes: z
+        .number()
+        .min(5)
+        .max(120)
+        .default(30)
+        .describe("How many minutes of history to search (5-120)"),
+    }),
+  },
+);

package/src/tools/betterstack-log.ts

@@ -0,0 +1,102 @@
+/**
+ * Better Stack log query tool.
+ */
+
+import * as logger from "@easyoref/monitoring";
+import { config } from "@easyoref/shared";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+export const betterstackLogTool = tool(
+  async ({
+    query,
+    lastMinutes,
+  }: {
+    query: string;
+    lastMinutes: number;
+  }): Promise<string> => {
+    const token = config.logtailToken;
+    if (!token) {
+      return JSON.stringify({
+        error: "Better Stack token not configured",
+        hint: "Set observability.betterstack_token in config.yaml",
+      });
+    }
+
+    try {
+      const fromDate = new Date(Date.now() - lastMinutes * 60_000).toISOString();
+
+      const res = await fetch(
+        `https://in.logtail.com/queries/logs?query=${encodeURIComponent(query)}&from=${fromDate}&to=${new Date().toISOString()}&limit=20`,
+        {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+          },
+          signal: AbortSignal.timeout(8000),
+        },
+      );
+
+      if (!res.ok) {
+        const status = res.status;
+        if (status === 401 || status === 403) {
+          return JSON.stringify({
+            error: "Invalid Better Stack credentials",
+            hint: "Check your observability.betterstack_token in config.yaml",
+          });
+        }
+        return JSON.stringify({
+          error: `Better Stack API returned ${status}`,
+          retry: status >= 500,
+        });
+      }
+
+      const json = (await res.json()) as {
+        results?: Array<{ message: string; timestamp: string }>;
+      };
+      const logs = json.results ?? [];
+
+      const formattedLogs = logs.map((entry) => ({
+        timestamp: entry.timestamp,
+        message: entry.message.slice(0, 500),
+      }));
+
+      logger.info("Tool: betterstack_log executed", {
+        query,
+        last_minutes: lastMinutes,
+        returned: logs.length,
+      });
+
+      return JSON.stringify({
+        query,
+        logs: formattedLogs,
+        count: logs.length,
+      });
+    } catch (err) {
+      logger.warn("Tool: betterstack_log failed", { error: String(err) });
+      return JSON.stringify({
+        error: `Better Stack query failed: ${String(err)}`,
+        retry: true,
+      });
+    }
+  },
+  {
+    name: "betterstack_log",
+    description:
+      "Query recent EasyOref logs from Better Stack (formerly Logtail). " +
+      "Use to check: what happened in the enrichment pipeline recently, " +
+      "any errors or unusual patterns. " +
+      "Good for debugging: 'why did this alert enrichment fail?'",
+    schema: z.object({
+      query: z
+        .string()
+        .describe("Search query for log messages (e.g. 'error', 'alert-123')"),
+      lastMinutes: z
+        .number()
+        .min(5)
+        .max(1440)
+        .default(30)
+        .describe("How many minutes back to search (5-1440)"),
+    }),
+  },
+);

package/src/tools/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool re-exports for agentic clarification.
+ */
+
+export { readSourcesTool } from "./read-sources.js";
+export { alertHistoryTool, formatOrefDate } from "./alert-history.js";
+export { resolveAreaTool, resolveAreaProximity } from "./resolve-area.js";
+export { betterstackLogTool } from "./betterstack-log.js";
+
+export { resolveAreaProximity as _resolveAreaProximity } from "./resolve-area.js";
+export { formatOrefDate as _formatOrefDate } from "./alert-history.js";
+
+import { readSourcesTool } from "./read-sources.js";
+import { alertHistoryTool } from "./alert-history.js";
+import { resolveAreaTool } from "./resolve-area.js";
+import { betterstackLogTool } from "./betterstack-log.js";
+
+export const clarifyTools = [
+  readSourcesTool,
+  alertHistoryTool,
+  resolveAreaTool,
+  betterstackLogTool,
+];

package/src/tools/read-sources.ts

@@ -0,0 +1,86 @@
+/**
+ * Telegram sources tool — fetch recent posts from a channel.
+ */
+
+import { fetchRecentChannelPosts } from "@easyoref/gramjs";
+import * as logger from "@easyoref/monitoring";
+import { config } from "@easyoref/shared";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+export const readSourcesTool = tool(
+  async ({
+    channel,
+    limit,
+  }: {
+    channel: string;
+    limit: number;
+  }): Promise<string> => {
+    try {
+      const safeLimit = Math.min(limit, config.agent.clarifyFetchCount);
+      const posts = await fetchRecentChannelPosts(channel, safeLimit);
+
+      if (posts.length === 0) {
+        return JSON.stringify({
+          channel,
+          posts: [],
+          note: "No recent posts found or channel not accessible",
+        });
+      }
+
+      const result = {
+        channel,
+        posts: posts.map(
+          (p: { text: string; ts: number; messageUrl?: string }) => ({
+            text: p.text.slice(0, 800),
+            ts: p.ts,
+            messageUrl: p.messageUrl,
+          }),
+        ),
+        count: posts.length,
+      };
+
+      logger.info("Tool: read_telegram_sources executed", {
+        channel,
+        limit: safeLimit,
+        returned: posts.length,
+      });
+
+      return JSON.stringify(result);
+    } catch (err) {
+      const errStr = String(err);
+      const isRateLimit =
+        errStr.includes("FLOOD") || errStr.includes("rate limit");
+
+      logger.warn("Tool: read_telegram_sources failed", {
+        channel,
+        error: errStr,
+      });
+
+      return JSON.stringify({
+        error: `Failed to fetch from ${channel}: ${errStr}`,
+        retry: !isRateLimit,
+      });
+    }
+  },
+  {
+    name: "read_telegram_sources",
+    description:
+      "Fetch last 1-4 posts from a Telegram news channel via MTProto. " +
+      "Returns actual message texts you can extract data from. " +
+      "Authoritative channels: @idf_telegram (IDF official), @N12LIVE (news), " +
+      "@israelsecurity (security), @ynetalerts (Ynet). " +
+      "Use when existing sources contradict each other or you need confirmation.",
+    schema: z.object({
+      channel: z
+        .string()
+        .describe("Channel username with @ prefix (e.g. @idf_telegram)"),
+      limit: z
+        .number()
+        .min(1)
+        .max(4)
+        .default(3)
+        .describe("Number of recent posts to fetch (1-4)"),
+    }),
+  },
+);

package/src/tools/resolve-area.ts

@@ -0,0 +1,202 @@
+/**
+ * Resolve area relevance tool — check if location is in user's defense zone.
+ */
+
+import * as logger from "@easyoref/monitoring";
+import { config } from "@easyoref/shared";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+const AREA_PROXIMITY_GROUPS: Record<string, string[]> = {
+  "גוש דן": [
+    "תל אביב", "רמת גן", "גבעתיים", "בני ברק", "חולון", "בת ים",
+    "פתח תקווה", "גבעת שמואל", "אור יהודה", "יהוד", "קריית אונו",
+  ],
+  שרון: ["הרצליה", "רעננה", "כפר סבא", "הוד השרון", "נתניה", "רמת השרון", "כוכב יאיר"],
+  מרכז: ["ראשון לציון", "רחובות", "נס ציונה", "לוד", "רמלה", "מודיעין", "יבנה", "שוהם"],
+  ירושלים: ["ירושלים", "בית שמש", "מעלה אדומים", "מבשרת ציון"],
+  חיפה: ["חיפה", "קריות", "קריית אתא", "קריית ביאליק", "קריית מוצקין", "טירת כרמל", "נשר"],
+  "דרום-מערב": ["אשקלון", "אשדוד", "גן יבנה", "קריית מלאכי"],
+  "עוטף עזה": ["שדרות", "עוטף עזה", "נתיבות", "אופקים"],
+  "באר שבע": ["באר שבע", "ערד", "דימונה"],
+  "גליל עליון": ["קריית שמונה", "מטולה", "צפת", "ראש פינה"],
+};
+
+function resolveAreaProximity(
+  mentioned: string,
+  monitoredAreas: string[],
+): {
+  relevant: boolean;
+  sameZone: string | undefined;
+  monitoredMatch: string[];
+  reasoning: string;
+} {
+  const normalizedMentioned = mentioned.toLowerCase().trim();
+  const normalizedMentionedHebrew = mentioned.replace(/\s+/g, "");
+
+  for (const area of monitoredAreas) {
+    const normalizedArea = area.toLowerCase().trim();
+    const normalizedAreaHebrew = area.replace(/\s+/g, "");
+
+    if (
+      normalizedMentioned === normalizedArea ||
+      normalizedMentioned.includes(normalizedArea) ||
+      normalizedArea.includes(normalizedMentioned) ||
+      normalizedMentionedHebrew === normalizedAreaHebrew ||
+      normalizedMentionedHebrew.includes(normalizedAreaHebrew)
+    ) {
+      return {
+        relevant: true,
+        sameZone: undefined,
+        monitoredMatch: [area],
+        reasoning: `"${mentioned}" directly matches monitored area "${area}"`,
+      };
+    }
+  }
+
+  for (const [zone, cities] of Object.entries(AREA_PROXIMITY_GROUPS)) {
+    const mentionedNormalized = mentioned.toLowerCase();
+    const mentionedHebrew = mentioned.replace(/\s+/g, "");
+
+    for (const city of cities) {
+      const cityNormalized = city.toLowerCase();
+      const cityHebrew = city.replace(/\s+/g, "");
+
+      if (
+        mentionedNormalized === cityNormalized ||
+        mentionedNormalized.includes(cityNormalized) ||
+        cityNormalized.includes(mentionedNormalized) ||
+        mentionedHebrew === cityHebrew ||
+        mentionedHebrew.includes(cityHebrew)
+      ) {
+        const matchedMonitored = monitoredAreas.filter((mArea) => {
+          const mAreaNormalized = mArea.toLowerCase().replace(/\s+/g, "");
+          return cities.some(
+            (c) =>
+              c.toLowerCase().replace(/\s+/g, "") === mAreaNormalized ||
+              mAreaNormalized.includes(c.toLowerCase().replace(/\s+/g, "")) ||
+              c.toLowerCase().replace(/\s+/g, "").includes(mAreaNormalized),
+          );
+        });
+
+        if (matchedMonitored.length > 0) {
+          return {
+            relevant: true,
+            sameZone: zone,
+            monitoredMatch: matchedMonitored,
+            reasoning:
+              `"${mentioned}" is in zone "${zone}" together with monitored: ` +
+              matchedMonitored.join(", "),
+          };
+        }
+
+        return {
+          relevant: false,
+          sameZone: zone,
+          monitoredMatch: [],
+          reasoning:
+            `"${mentioned}" is in zone "${zone}" but none of user's monitored ` +
+            `areas (${monitoredAreas.join(", ")}) are in that zone`,
+        };
+      }
+    }
+  }
+
+  return {
+    relevant: false,
+    sameZone: undefined,
+    monitoredMatch: [],
+    reasoning:
+      `"${mentioned}" could not be matched to any monitored area ` +
+      `(${monitoredAreas.join(", ")})`,
+  };
+}
+
+const REGION_KEYWORDS: Record<string, string[]> = {
+  מרכז: ["תל אביב", "רמת גן", "פתח תקווה", "ראשון לציון", "הרצליה", "חולון"],
+  צפון: ["חיפה", "קריות", "צפת", "קריית שמונה", "נצרת", "עכו", "טבריה"],
+  דרום: ["באר שבע", "אשדוד", "אשקלון", "שדרות", "אילת"],
+};
+
+function resolveAreaProximityWithRegions(
+  mentioned: string,
+  monitoredAreas: string[],
+): {
+  relevant: boolean;
+  sameZone: string | undefined;
+  monitoredMatch: string[];
+  reasoning: string;
+} {
+  const baseResult = resolveAreaProximity(mentioned, monitoredAreas);
+  if (baseResult.relevant) {
+    return baseResult;
+  }
+
+  const mentionedLower = mentioned.toLowerCase();
+
+  for (const [region, cities] of Object.entries(REGION_KEYWORDS)) {
+    if (!mentionedLower.includes(region)) continue;
+    const matchedMonitored = monitoredAreas.filter((m) =>
+      cities.some((c) => m.includes(c) || c.includes(m.split(" ")[0] ?? "")),
+    );
+    if (matchedMonitored.length > 0) {
+      return {
+        relevant: true,
+        sameZone: region,
+        monitoredMatch: matchedMonitored,
+        reasoning:
+          `"${mentioned}" refers to region "${region}" which includes ` +
+          matchedMonitored.join(", "),
+      };
+    }
+  }
+
+  return baseResult;
+}
+
+export { resolveAreaProximityWithRegions as resolveAreaProximity };
+
+export const resolveAreaTool = tool(
+  async ({ location }: { location: string }): Promise<string> => {
+    const monitoredAreas = config.areas;
+
+    if (monitoredAreas.length === 0) {
+      return JSON.stringify({
+        error: "No monitored areas configured",
+        hint: "User has not set up city monitoring",
+      });
+    }
+
+    const result = resolveAreaProximityWithRegions(location, monitoredAreas);
+
+    logger.info("Tool: resolve_area executed", {
+      location,
+      relevant: result.relevant,
+      zone: result.sameZone,
+    });
+
+    return JSON.stringify({
+      location,
+      monitored_areas: monitoredAreas,
+      ...result,
+    });
+  },
+  {
+    name: "resolve_area",
+    description:
+      "Determine if a location mentioned in news is relevant to the user's " +
+      "monitored areas. Uses defense-zone proximity: cities in the same Iron Dome " +
+      "coverage zone are considered relevant. " +
+      'Example: "попадание в Петах Тикве" → relevant for Herzliya user ' +
+      "(both in Gush Dan / Sharon zone). " +
+      'Use when a news post mentions a city or region like "center" and you need ' +
+      "to determine if it affects the user.",
+    schema: z.object({
+      location: z
+        .string()
+        .describe(
+          "City or region name in Hebrew as mentioned in news (e.g. פתח תקווה, מרכז)",
+        ),
+    }),
+  },
+);

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "references": [
+    { "path": "../shared" },
+    { "path": "../monitoring" },
+    { "path": "../gramjs" }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["src/**/__tests__/**", "src/**/*.test.ts", "dist"]
+}