@easyoref/agent 1.21.1

package/dist/worker.js

@@ -0,0 +1,135 @@
+/**
+ * BullMQ worker — processes "enrich-alert" jobs.
+ *
+ * Session-aware scheduling:
+ *   early_warning → every 20s, up to 30 min
+ *   siren         → every 20s, up to 15 min
+ *   resolved      → every 60s, up to 10 min (tail — detailed intel)
+ *
+ * After each job, checks the session phase and re-enqueues
+ * with the appropriate delay. Stops when phase expires.
+ */
+import * as logger from "@easyoref/monitoring";
+import { clearSession, config, getActiveSession, getLanguagePack, isPhaseExpired, PHASE_ENRICH_DELAY_MS, } from "@easyoref/shared";
+import { Worker } from "bullmq";
+import { Bot } from "grammy";
+import { runEnrichment } from "./graph.js";
+import { MONITORING_RE, stripMonitoring } from "./nodes/edit-node.js";
+import { enqueueEnrich } from "./runtime/queue.js";
+let _worker = undefined;
+/** Remove ⏳ monitoring indicator from all chat messages (best-effort) */
+async function removeMonitoringIndicator(session) {
+    if (!config.botToken || !MONITORING_RE.test(session.currentText))
+        return;
+    const cleaned = stripMonitoring(session.currentText);
+    const tgBot = new Bot(config.botToken);
+    const targets = session.telegramMessages ?? [
+        {
+            chatId: session.chatId,
+            messageId: session.latestMessageId,
+            isCaption: session.isCaption,
+        },
+    ];
+    for (const cm of targets) {
+        try {
+            if (cm.isCaption) {
+                await tgBot.api.editMessageCaption(cm.chatId, cm.messageId, {
+                    caption: cleaned,
+                    parse_mode: "HTML",
+                });
+            }
+            else {
+                await tgBot.api.editMessageText(cm.chatId, cm.messageId, cleaned, {
+                    parse_mode: "HTML",
+                });
+            }
+        }
+        catch (err) {
+            const errStr = String(err);
+            if (!errStr.includes("message is not modified")) {
+                logger.error("Failed to remove monitoring indicator", {
+                    error: errStr,
+                    chatId: cm.chatId,
+                });
+            }
+        }
+    }
+    logger.info("Removed monitoring indicator", { targets: targets.length });
+}
+export function startEnrichWorker() {
+    if (!config.agent.enabled)
+        return;
+    const connection = {
+        host: new URL(config.agent.redisUrl).hostname,
+        port: Number(new URL(config.agent.redisUrl).port || 6379),
+        password: new URL(config.agent.redisUrl).password || undefined,
+    };
+    _worker = new Worker("enrich-alert", async (job) => {
+        const { alertId } = job.data;
+        logger.info("Enrich worker: processing job", { alertId, jobId: job.id });
+        const session = await getActiveSession();
+        if (!session) {
+            logger.info("Enrich worker: no active session — skipping", { alertId });
+            return;
+        }
+        // Phase expired → end session
+        if (isPhaseExpired(session)) {
+            logger.info("Enrich worker: phase expired — ending session", {
+                alertId: session.latestAlertId,
+                phase: session.phase,
+            });
+            await removeMonitoringIndicator(session);
+            await clearSession();
+            return;
+        }
+        const langPack = getLanguagePack(config.language);
+        // Run enrichment using latest alert's message as edit target
+        await runEnrichment({
+            alertId: session.latestAlertId,
+            alertTs: session.latestAlertTs,
+            alertType: session.phase,
+            alertAreas: session.alertAreas,
+            chatId: session.chatId,
+            messageId: session.latestMessageId,
+            isCaption: session.isCaption,
+            telegramMessages: session.telegramMessages,
+            currentText: session.baseText ?? session.currentText,
+            monitoringLabel: langPack.labels.monitoring,
+        });
+        // Re-check session after enrichment (may have changed phase)
+        const after = await getActiveSession();
+        if (!after)
+            return;
+        if (isPhaseExpired(after)) {
+            logger.info("Enrich worker: phase expired post-enrich — ending session", {
+                phase: after.phase,
+            });
+            await removeMonitoringIndicator(after);
+            await clearSession();
+            return;
+        }
+        // Re-enqueue with phase-appropriate delay
+        const delay = PHASE_ENRICH_DELAY_MS[after.phase];
+        await enqueueEnrich(after.latestAlertId, after.latestAlertTs, delay);
+    }, {
+        connection,
+        concurrency: 1,
+    });
+    _worker.on("completed", (job) => {
+        logger.info("Enrich worker: job completed", { jobId: job.id });
+    });
+    _worker.on("failed", (job, err) => {
+        logger.error("Enrich worker: job failed", {
+            jobId: job?.id,
+            error: String(err),
+        });
+    });
+    logger.info("Enrich worker started");
+}
+export async function stopEnrichWorker() {
+    if (_worker) {
+        await _worker.close();
+        _worker = undefined;
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@easyoref/agent",
+  "version": "1.21.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.1.31",
+    "@langchain/langgraph": "^1.2.1",
+    "@langchain/openai": "^1.2.12",
+    "bullmq": "^5.0.0",
+    "ioredis": "^5.3.0",
+    "@easyoref/shared": "*",
+    "@easyoref/monitoring": "*",
+    "@easyoref/gramjs": "*",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/graph.ts

@@ -0,0 +1,200 @@
+/**
+ * LangGraph.js enrichment pipeline — phase-aware, time-validated.
+ *
+ * ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌──────────---──┐
+ * │ filter  │───▶│ extract │───▶│  vote   │───▶│ shouldClarify │
+ * └─────────┘    └─────────┘    └─────────┘    └──────┬───---──┘
+ *                                                     │
+ *                                      ┌──────────────┴──────────────┐
+ *                                      │                             │
+ *                                 [low conf]                    [high conf]
+ *                                      │                             │
+ *                                      ▼                             ▼
+ *                               ┌────────────┐                  ┌─────────┐
+ *                               │  clarify   │                  │   edit  │
+ *                               └──────┬─────┘                  └─────────┘
+ *                                      │                             ▲
+ *                                      ▼                             │
+ *                               ┌────────────┐                       │
+ *                               │   revote   │───────────────────────┘
+ *                               └────────────┘
+ *
+ * ── Node responsibilities ──────────────────────────────────────────────────
+ *
+ * filter:     Collect Telegram posts from Redis, apply deterministic noise
+ *             filters (area lists, summaries, IDF press releases). Returns
+ *             ChannelTracking structure.
+ *
+ * extract:    LLM-powered extraction pipeline:
+ *             1. Cheap model → which channels have relevant intel?
+ *             2. Expensive model → extract structured data per post
+ *             3. Post-filter → deterministic validation
+ *
+ * vote:       Consensus voting (deterministic, 0 tokens). Aggregates multiple
+ *             extractions into a single VotedResult using median/majority.
+ *
+ * shouldClarify: Conditional routing:
+ *             - Low confidence (< threshold) → clarify
+ *             - Single-source Lebanon for central Israel → clarify (suspicious)
+ *             - Already clarified → edit
+ *             - MCP tools disabled → edit
+ *
+ * clarify:    ReAct agent with tools (read_telegram, alert_history,
+ *             resolve_area, betterstack_log). Fetches more data to resolve
+ *             contradictions. Output: new extractions.
+ *
+ * revote:     Re-run vote with additional extractions from clarify.
+ *
+ * edit:       Build enriched message text and edit Telegram message.
+ *
+ * ── Why this pipeline? ─────────────────────────────────────────────────────
+ *
+ * 1. Cheap → Expensive: Saves tokens. Pre-filter with cheap model ($0.001)
+ *    before spending on per-post extraction ($0.01 each).
+ *
+ * 2. ReAct clarification: Low-confidence results aren't "failed" —
+ *    they're signals that more data is needed. The LLM decides what tools
+ *    to use rather than a hardcoded threshold.
+ *
+ * 3. Carry-forward: previousEnrichment preserves data between phases.
+ *    If origin was confirmed in early_warning, it carries to red_alert/resolved.
+ *
+ * 4. Time validation: LLM instructions emphasize checking if sources
+ *    are about THIS alert vs. previous attacks. Critical for accuracy.
+ */
+
+import * as logger from "@easyoref/monitoring";
+import {
+  AlertTypeSchema,
+  ChannelTrackingSchema,
+  EnrichmentDataSchema,
+  RunEnrichmentInputSchema,
+  TelegramMessageSchema,
+  ValidatedExtractionSchema,
+  VotedResultSchema,
+  config,
+  createEmptyEnrichmentData,
+  validateSafe,
+} from "@easyoref/shared";
+import {
+  END,
+  MemorySaver,
+  ReducedValue,
+  START,
+  StateGraph,
+  StateSchema,
+} from "@langchain/langgraph";
+import { z } from "zod";
+import { clarifyNode } from "./nodes/clarify-node.js";
+import { editNode } from "./nodes/edit-node.js";
+import { extractNode } from "./nodes/extract-node.js";
+import { filterNode } from "./nodes/filter-node.js";
+import { voteNode } from "./nodes/vote-node.js";
+
+export const AgentState = new StateSchema({
+  alertId: z.string(),
+  alertTs: z.number(),
+  alertType: AlertTypeSchema,
+  alertAreas: z.array(z.string()),
+  chatId: z.string(),
+  messageId: z.number(),
+  isCaption: z.boolean(),
+  currentText: z.string(),
+  tracking: ChannelTrackingSchema.optional(),
+  extractions: new ReducedValue(z.array(ValidatedExtractionSchema), {
+    reducer: (previous, current) => [...previous, ...current],
+  }),
+  votedResult: VotedResultSchema.optional(),
+  clarifyAttempted: z.boolean().default(false),
+  previousEnrichment: EnrichmentDataSchema.optional(),
+  monitoringLabel: z.string().optional(),
+  telegramMessages: new ReducedValue(z.array(TelegramMessageSchema), {
+    reducer: (previous, current) => [...previous, ...current],
+  }),
+});
+
+export type AgentStateType = typeof AgentState.State;
+
+const shouldClarify = (state: AgentStateType): "clarify" | "edit" => {
+  if (state.clarifyAttempted) return "edit";
+  if (!config.agent.mcpTools) return "edit";
+  if (!state.votedResult) return "edit";
+
+  if (state.votedResult.confidence < config.agent.confidenceThreshold) {
+    logger.info("Agent: routing to clarify (low confidence)", {
+      confidence: state.votedResult.confidence,
+    });
+    return "clarify";
+  }
+
+  const origins = state.votedResult.countryOrigins;
+  if (origins && origins.length === 1 && state.votedResult.sourcesCount === 1) {
+    if (
+      origins[0]!.name === "Lebanon" &&
+      state.alertAreas.some(
+        (area) =>
+          area.includes("תל אביב") ||
+          area.includes("גוש דן") ||
+          area.includes("שרון") ||
+          area.includes("מרכז"),
+      )
+    ) {
+      logger.info("Agent: routing to clarify (suspicious Lebanon origin)", {});
+      return "clarify";
+    }
+  }
+
+  return "edit";
+};
+
+const checkpointer = new MemorySaver();
+
+export const buildGraph = () =>
+  new StateGraph(AgentState)
+    .addNode("filter", filterNode)
+    .addNode("extract", extractNode)
+    .addNode("vote", voteNode)
+    .addNode("clarify", clarifyNode)
+    .addNode("revote", voteNode)
+    .addNode("edit", editNode)
+    .addEdge(START, "filter")
+    .addEdge("filter", "extract")
+    .addEdge("extract", "vote")
+    .addConditionalEdges("vote", shouldClarify, {
+      clarify: "clarify",
+      edit: "edit",
+    })
+    .addEdge("clarify", "revote")
+    .addEdge("revote", "edit")
+    .addEdge("edit", END)
+    .compile({ checkpointer });
+
+export type { RunEnrichmentInput } from "@easyoref/shared";
+export { RunEnrichmentInputSchema };
+
+export const runEnrichment = async (input: unknown): Promise<void> => {
+  const validation = validateSafe(RunEnrichmentInputSchema, input);
+  if (!validation.ok) {
+    logger.error("Enrichment: invalid input", { error: validation.error });
+    throw new Error(`Invalid enrichment input: ${validation.error}`);
+  }
+
+  const validInput = validation.data;
+
+  await buildGraph().invoke(
+    {
+      alertId: validInput.alertId,
+      alertTs: validInput.alertTs,
+      alertType: validInput.alertType,
+      alertAreas: validInput.alertAreas,
+      chatId: validInput.chatId,
+      messageId: validInput.messageId,
+      isCaption: validInput.isCaption,
+      telegramMessages: validInput.telegramMessages,
+      currentText: validInput.currentText,
+      previousEnrichment: createEmptyEnrichmentData(),
+      monitoringLabel: validInput.monitoringLabel,
+    },
+    { configurable: { thread_id: validInput.alertId } },
+  );
+};

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * EasyOref Agent Package
+ *
+ * LangGraph-based enrichment pipeline for Israeli missile alert processing.
+ */
+
+export * from "./graph.js";
+
+export * from "./nodes/clarify-node.js";
+export * from "./nodes/edit-node.js";
+export * from "./nodes/extract-node.js";
+export * from "./nodes/filter-node.js";
+export * from "./nodes/vote-node.js";
+
+export * from "./models.js";
+
+export * from "./runtime/auth.js";
+export * from "./runtime/dry-run.js";
+export * from "./runtime/queue.js";
+export * from "./runtime/redis.js";
+export * from "./runtime/worker.js";
+
+export { alertHistoryTool } from "./tools/alert-history.js";
+export { betterstackLogTool } from "./tools/betterstack-log.js";
+export { clarifyTools } from "./tools/index.js";
+export { readSourcesTool } from "./tools/read-sources.js";
+export { resolveAreaTool } from "./tools/resolve-area.js";

package/src/models.ts

@@ -0,0 +1,20 @@
+/**
+ * LLM models configuration.
+ */
+
+import { ChatOpenRouter } from "@langchain/openrouter";
+import { config } from "@easyoref/shared";
+
+export const filterModel = new ChatOpenRouter({
+  apiKey: config.agent.apiKey,
+  model: config.agent.filterModel,
+  temperature: 0,
+  maxTokens: 200,
+});
+
+export const extractModel = new ChatOpenRouter({
+  apiKey: config.agent.apiKey,
+  model: config.agent.extractModel,
+  temperature: 0,
+  maxTokens: 500,
+});

package/src/nodes/clarify-node.ts

@@ -0,0 +1,172 @@
+/**
+ * Clarify Node — optional ReAct tool calling for low-confidence enrichment.
+ */
+
+import * as logger from "@easyoref/monitoring";
+import {
+  ClarifyOutputSchema,
+  pushSessionPost,
+  type ChannelPost,
+  type ValidatedExtraction,
+} from "@easyoref/shared";
+import { createAgent, toolStrategy } from "langchain";
+import type { AgentStateType } from "../graph.js";
+import { filterModel } from "../models.js";
+import { clarifyTools } from "../tools/index.js";
+
+export const clarifyAgent = createAgent({
+  model: filterModel,
+  tools: clarifyTools,
+  responseFormat: toolStrategy(ClarifyOutputSchema),
+  systemPrompt: `
+  You are the clarification agent for EasyOref — an Israeli missile alert enrichment system.
+
+  The voting pipeline analyzed Telegram channel posts and produced a result with
+  low confidence or contradictions. You have access to 4 tools:
+
+    1. read_telegram_sources — fetch last N posts from a Telegram news channel
+    2. alert_history — get recent alert history from Pikud HaOref.
+    3. resolve_area — check if a location mentioned in news is relevant to user's areas.
+    4. betterstack_log — query recent EasyOref logs from Better Stack.
+
+  CRITICAL — TIME VALIDATION:
+  You receive the alert time (Israel timezone). Channel posts may be about PREVIOUS
+  attacks or ongoing military operations (not THIS specific alert). When in doubt:
+  - Use alert_history to verify if an alert really occurred at the claimed time/area.
+  - If a post discusses events from hours ago, it is STALE — ignore it.
+
+  You decide whether tools would help:
+  - If contradictions can be resolved with existing data → respond immediately, no tools.
+  - If an authoritative source (IDF, N12) could settle a disagreement → fetch 1-4 posts.
+  - If you need to verify whether an alert occurred → check alert_history.
+
+  Always respect an output format.
+  `,
+});
+
+function describeContradictions(
+  extractions: ValidatedExtraction[],
+  voted: {
+    countryOrigins?: { name: string }[];
+    rocketCountMin?: number;
+    rocketCountMax?: number;
+    interceptedConfidence?: number;
+    intercepted?: number;
+    hitsConfidence?: number;
+    hitsConfirmed?: number;
+    confidence: number;
+    sourcesCount: number;
+  },
+): string {
+  const issues: string[] = [];
+
+  if (voted.countryOrigins && voted.countryOrigins.length > 1) {
+    const names = voted.countryOrigins.map((c) => c.name).join(", ");
+    issues.push(`Multiple origin countries reported: ${names}`);
+  }
+
+  if (
+    voted.rocketCountMin &&
+    voted.rocketCountMax &&
+    voted.rocketCountMax - voted.rocketCountMin > 3
+  ) {
+    issues.push(
+      `Wide rocket count range: ${voted.rocketCountMin}–${voted.rocketCountMax}`,
+    );
+  }
+
+  if (
+    (voted.interceptedConfidence ?? 0) < 0.5 &&
+    voted.intercepted !== undefined
+  ) {
+    issues.push(
+      `Intercepted count (${voted.intercepted}) has low confidence: ${(
+        voted.interceptedConfidence ?? 0
+      ).toFixed(2)}`,
+    );
+  }
+
+  issues.push(`Overall confidence: ${voted.confidence}`);
+  issues.push(`Sources count: ${voted.sourcesCount}`);
+
+  return issues.join("\n");
+}
+
+export const clarifyNode = async (
+  state: AgentStateType,
+): Promise<Partial<AgentStateType>> => {
+  if (!state.votedResult) {
+    logger.info("Agent: clarify skipped — no voted result", {
+      alertId: state.alertId,
+    });
+    return { clarifyAttempted: true };
+  }
+
+  logger.info("Agent: clarify triggered", {
+    alertId: state.alertId,
+    confidence: state.votedResult.confidence,
+  });
+
+  try {
+    const contradictions = describeContradictions(
+      state.extractions,
+      state.votedResult,
+    );
+
+    const alertTimeIL = new Date(state.alertTs).toLocaleTimeString("he-IL", {
+      hour: "2-digit",
+      minute: "2-digit",
+      timeZone: "Asia/Jerusalem",
+    });
+
+    const userPrompt =
+      `Alert region: ${state.alertAreas.join(", ")}\n` +
+      `Alert type: ${state.alertType}\n` +
+      `Alert time: ${alertTimeIL} (Israel)\n` +
+      `Message ID: ${state.messageId}\n\n` +
+      `Current voted result:\n` +
+      JSON.stringify(state.votedResult, undefined, 2) +
+      `\n\nContradictions & issues:\n${contradictions}\n\n` +
+      `Existing extractions (${
+        state.extractions.filter((e) => e.valid).length
+      } valid):\n` +
+      state.extractions
+        .filter((e) => e.valid)
+        .map(
+          (e) =>
+            `  [${e.channel}] country=${e.countryOrigin}, rockets=${e.rocketCount}, ` +
+            `intercepted=${e.intercepted}, hits=${e.hitsConfirmed}, conf=${e.confidence}`,
+        )
+        .join("\n") +
+      `\n\nDecide: would fetching more data from authoritative channels resolve these issues?`;
+
+    const result = await clarifyAgent.invoke({ messages: [userPrompt] });
+    const output = result.structuredResponse;
+
+    const newPosts: ChannelPost[] = [];
+    if (output?.newPosts) {
+      for (const p of output.newPosts) {
+        const post: ChannelPost = {
+          channel: p.channel,
+          text: p.text,
+          ts: p.ts,
+          messageUrl: p.messageUrl,
+        };
+        newPosts.push(post);
+        await pushSessionPost(post);
+      }
+    }
+
+    return {
+      extractions: [...state.extractions, ...(output?.newExtractions ?? [])],
+      votedResult: undefined,
+      clarifyAttempted: true,
+    };
+  } catch (err) {
+    logger.error("Agent: clarify failed", {
+      alertId: state.alertId,
+      error: String(err),
+    });
+    return { clarifyAttempted: true };
+  }
+};