From ef1584e4a9291f3bea68363477534e8bcaced88b Mon Sep 17 00:00:00 2001
From: asemabdallah <asasem547@gmail.com>
Date: Wed, 7 Oct 2026 00:04:30 +0200
Subject: [PATCH] feature: show what changed when a watched page changes

---
 apps/server/src/engine/page-diff.ts |  85 ++++++++++++++++++
 apps/server/src/engine/service.ts   |  45 +++++++++-
 tests/agent-api.test.ts             | 133 ++++++++++++++++++++++++++++
 tests/page-diff.test.ts             | 106 ++++++++++++++++++++++
 4 files changed, 365 insertions(+), 4 deletions(-)
 create mode 100644 apps/server/src/engine/page-diff.ts
 create mode 100644 tests/page-diff.test.ts

diff --git a/apps/server/src/engine/page-diff.ts b/apps/server/src/engine/page-diff.ts
new file mode 100644
index 00000000..b5164732
--- /dev/null
+++ b/apps/server/src/engine/page-diff.ts
@@ -0,0 +1,85 @@
+/** Lines of page text for comparing two checks of a watched page. */
+export function pageLines(text: string, limit = 2000): string[] {
+  const lines = new Set<string>();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.replace(/\s+/g, " ").trim().slice(0, 300);
+    if (line) lines.add(line);
+    if (lines.size >= limit) break;
+  }
+  return [...lines];
+}
+
+export type PageDiff = { added: string[]; updated: string[]; removed: string[] };
+
+// Relative times ("posted 1 day ago" → "posted 2 days ago", "58 minutes ago" → "1 hour ago")
+// tick on their own, so a change in them alone is not news.
+const relativeTime =
+  /\b(?:\d+|an?|one)\s+(?:sec(?:ond)?|min(?:ute)?|hour|hr|day|week|month|year)s?\s+ago\b|\bvor\s+(?:\d+|einer?|einem)\s+(?:sekunde|minute|stunde|tag|woche|monat|jahr)(?:e|en|n)?\b/giu;
+
+/** Text with relative times blanked out: equal results mean only those times changed. */
+export function withoutRelativeTimes(text: string) {
+  return text.replace(relativeTime, "<time>");
+}
+
+// Any other number change (a price, stock count or version) is news, listed as an update.
+const numberless = (line: string) =>
+  withoutRelativeTimes(line)
+    .replace(/\d+(?:[.,]\d+)*/g, "#")
+    .replace(/(\p{L})s\b/gu, "$1")
+    .toLowerCase();
+
+/**
+ * Pairs each current line with one unused previous line of the same key, so one remaining
+ * line can never account for another that was removed.
+ */
+function pair(previous: string[], current: string[], key: (line: string) => string) {
+  const open = new Map<string, string[]>();
+  for (const line of previous) open.set(key(line), [...(open.get(key(line)) ?? []), line]);
+  const used = new Set<string>();
+  const paired: string[] = [];
+  const unpaired: string[] = [];
+  for (const line of current) {
+    const match = open.get(key(line))?.shift();
+    if (match === undefined) unpaired.push(line);
+    else {
+      used.add(match);
+      paired.push(line);
+    }
+  }
+  return { paired, unpaired, left: previous.filter((line) => !used.has(line)) };
+}
+
+export function diffPage(previous: string[], current: string[]): PageDiff {
+  const same = pair(previous, current, (line) => line);
+  // A line where only a relative time changed is left out.
+  const retimed = pair(same.left, same.unpaired, withoutRelativeTimes);
+  const renumbered = pair(retimed.left, retimed.unpaired, numberless);
+  return { added: renumbered.unpaired, updated: renumbered.paired, removed: renumbered.left };
+}
+
+/** A short "New / Updated / Removed" summary, or "" when no line changed. */
+export function describePageDiff(diff: PageDiff) {
+  const section = (title: string, lines: string[], limit: number) => {
+    if (!lines.length) return [];
+    const shown = lines.slice(0, limit).map((line) => `• ${line.slice(0, 160)}`);
+    const more = lines.length > limit ? [`+${lines.length - limit} more`] : [];
+    return [`${title}:`, ...shown, ...more];
+  };
+  return [
+    ...section("New", diff.added, 8),
+    ...section("Updated", diff.updated, 4),
+    ...section("Removed", diff.removed, 4),
+  ].join("\n");
+}
+
+/** A one-line count for task results, such as "3 lines changed (2 new, 1 updated)". */
+export function countPageDiff(diff: PageDiff) {
+  const total = diff.added.length + diff.updated.length + diff.removed.length;
+  if (!total) return "";
+  const parts = [
+    diff.added.length && `${diff.added.length} new`,
+    diff.updated.length && `${diff.updated.length} updated`,
+    diff.removed.length && `${diff.removed.length} removed`,
+  ].filter(Boolean);
+  return `${total} line${total === 1 ? "" : "s"} changed (${parts.join(", ")})`;
+}
diff --git a/apps/server/src/engine/service.ts b/apps/server/src/engine/service.ts
index 3c31d7fc..d77706c3 100644
--- a/apps/server/src/engine/service.ts
+++ b/apps/server/src/engine/service.ts
@@ -35,9 +35,18 @@ import { SearchService } from "../search.ts";
 import type { WorkspaceService } from "../workspace.ts";
 import { analyzeSpending } from "./finance.ts";
 import { executeModelTask } from "./model.ts";
+import {
+  countPageDiff,
+  describePageDiff,
+  diffPage,
+  pageLines,
+  withoutRelativeTimes,
+} from "./page-diff.ts";
 import { LostLeaseError, type TaskContext, TaskWorker } from "./worker.ts";
 
 const hash = (text: string) => createHash("sha256").update(text).digest("hex");
+/** A change watch's last saved page: its hash, relative-time-free fingerprint and lines. */
+type MonitorPage = { id: string; hash?: string; timelessHash?: string; lines: string[] };
 const date = () => new Date().toISOString();
 const terminal = new Set(["succeeded", "failed", "cancelled"]);
 export class AgentService {
@@ -1074,7 +1083,23 @@ export class AgentService {
           ? text.toLowerCase().includes(monitor.value.toLowerCase())
           : this.matchesPrice(text, Number(monitor.value));
     const previouslyMatched = Boolean(task.state.matched);
-    const shouldNotify = matched && (monitor.condition === "change" || !previouslyMatched);
+    // For change watches, keep the page lines and a relative-time-free fingerprint of the whole text.
+    const change = monitor.condition === "change";
+    const lines = change ? pageLines(observation.text) : [];
+    const timelessHash = change ? hash(withoutRelativeTimes(text)) : undefined;
+    const savedPage =
+      matched && change
+        ? await this.db.get<MonitorPage>(owner, "monitor-pages", monitor.id)
+        : undefined;
+    // Saved lines can run ahead of a lost task outcome; use them only for the committed baseline.
+    const baseline = savedPage?.hash === previousHash ? savedPage : undefined;
+    // Only relative times changed anywhere on the page ("3 minutes ago"): keep watching quietly.
+    const quiet = Boolean(baseline?.timelessHash && baseline.timelessHash === timelessHash);
+    const shouldNotify =
+      matched && !quiet && (monitor.condition === "change" || !previouslyMatched);
+    const diff = baseline && shouldNotify ? diffPage(baseline.lines, lines) : undefined;
+    // Empty when the change is past the saved lines; the alert then quotes the page instead.
+    const changes = diff ? describePageDiff(diff) : "";
     // A notification-worthy observation is a new event, even when the page text is
     // identical to an earlier one (a change back to a seen state, or a condition that
     // cleared and reappeared). Commit its sequence with the outcome so publication
@@ -1098,6 +1123,13 @@ export class AgentService {
       },
     );
     if (!savedMonitor) throw new LostLeaseError();
+    if (change)
+      await this.db.put(owner, "monitor-pages", {
+        id: monitor.id,
+        hash: currentHash,
+        timelessHash,
+        lines,
+      });
     await ctx.event(
       "observation",
       previousHash ? "Checked for changes" : "Saved the first observation",
@@ -1105,13 +1137,16 @@ export class AgentService {
     );
     if (shouldNotify) {
       await ctx.guard();
-      await ctx.event("result", "A meaningful change was found", text.slice(0, 500));
+      await ctx.event("result", "A meaningful change was found", changes || text.slice(0, 500));
     }
+    const count = diff ? countPageDiff(diff) : "";
     return {
       status: "scheduled",
       nextRunAt: nextCheckAt,
       result: shouldNotify
-        ? "Change found. A notification is ready."
+        ? count
+          ? `Change found: ${count}. A notification is ready.`
+          : "Change found. A notification is ready."
         : "Watching. I'll check again on schedule.",
       state: {
         ...task.state,
@@ -1124,7 +1159,9 @@ export class AgentService {
         notice: shouldNotify
           ? {
               title: monitor.title,
-              body: `Condition met at ${observation.url}: ${text.slice(0, 240)}`,
+              body: changes
+                ? `Changed at ${observation.url}\n${changes}`
+                : `Condition met at ${observation.url}: ${text.slice(0, 240)}`,
               key: `monitor:${monitor.id}:${alertSequence}:${currentHash}`,
             }
           : null,
diff --git a/tests/agent-api.test.ts b/tests/agent-api.test.ts
index 953f77e3..1df33a22 100644
--- a/tests/agent-api.test.ts
+++ b/tests/agent-api.test.ts
@@ -449,3 +449,136 @@ test("manual milestone completion preserves current titles, ordering and concurr
     404,
   );
 });
+
+test("a change watch alert lists the new and updated lines of the page", async () => {
+  await read("/sample-page", {
+    text: "AI jobs in Munich\nSiemens · Werkstudent AI · 2 openings\nBCG · Intern",
+  });
+  const monitor = await read<Monitor>(
+    "/monitors",
+    {
+      title: "Munich AI jobs",
+      url: "sample://availability",
+      condition: "change",
+      intervalMinutes: 1,
+    },
+    201,
+  );
+  await server.agent.worker.tick();
+  await read("/sample-page", {
+    text: "AI jobs in Munich\nSAP · Working Student AI Engineer\nSiemens · Werkstudent AI · 3 openings\nBCG · Intern",
+  });
+  await read(`/monitors/${monitor.id}/control`, { action: "check" });
+  await server.agent.worker.tick();
+  const [alert] = (await read<AgentNotification[]>("/notifications")).filter(
+    (item) => item.taskId === monitor.taskId,
+  );
+  assert.equal(
+    alert?.body,
+    "Changed at sample://availability\nNew:\n• SAP · Working Student AI Engineer\nUpdated:\n• Siemens · Werkstudent AI · 3 openings",
+  );
+  const { task } = await read<{ task: AgentTask }>(`/tasks/${monitor.taskId}`);
+  assert.equal(
+    task.result,
+    "Change found: 2 lines changed (1 new, 1 updated). A notification is ready.",
+  );
+  await read(`/monitors/${monitor.id}/control`, { action: "stop" });
+});
+
+test("a change watch stays quiet when only relative times change", async () => {
+  await read("/sample-page", { text: "Jobs\nSiemens · Werkstudent AI · 3 minutes ago" });
+  const monitor = await read<Monitor>(
+    "/monitors",
+    { title: "Quiet jobs", url: "sample://availability", condition: "change", intervalMinutes: 1 },
+    201,
+  );
+  const alerts = async () =>
+    (await read<AgentNotification[]>("/notifications")).filter(
+      (item) => item.taskId === monitor.taskId,
+    );
+  await server.agent.worker.tick();
+  for (const text of [
+    "Jobs\nSiemens · Werkstudent AI · 58 minutes ago",
+    "Jobs\nSiemens · Werkstudent AI · 1 hour ago",
+  ]) {
+    await read("/sample-page", { text });
+    await read(`/monitors/${monitor.id}/control`, { action: "check" });
+    await server.agent.worker.tick();
+  }
+  assert.equal((await alerts()).length, 0, "ticking timestamps are not news");
+  await read("/sample-page", {
+    text: "Jobs\nSAP · Working Student AI\nSiemens · Werkstudent AI · 2 hours ago",
+  });
+  await read(`/monitors/${monitor.id}/control`, { action: "check" });
+  await server.agent.worker.tick();
+  const [alert] = await alerts();
+  assert.match(alert?.body ?? "", /New:\n• SAP · Working Student AI/);
+  await read(`/monitors/${monitor.id}/control`, { action: "stop" });
+});
+
+test("a change watch alerts when only a price changes", async () => {
+  await read("/sample-page", { text: "Headphones\nPrice: $399.99\nOnly 3 left" });
+  const monitor = await read<Monitor>(
+    "/monitors",
+    { title: "Headphones", url: "sample://availability", condition: "change", intervalMinutes: 1 },
+    201,
+  );
+  await server.agent.worker.tick();
+  await read("/sample-page", { text: "Headphones\nPrice: $279.99\nOnly 3 left" });
+  await read(`/monitors/${monitor.id}/control`, { action: "check" });
+  await server.agent.worker.tick();
+  const alerts = (await read<AgentNotification[]>("/notifications")).filter(
+    (item) => item.taskId === monitor.taskId,
+  );
+  assert.equal(alerts.length, 1, "a price change is news");
+  assert.equal(alerts[0]?.body, "Changed at sample://availability\nUpdated:\n• Price: $279.99");
+  await read(`/monitors/${monitor.id}/control`, { action: "stop" });
+});
+
+test("a change watch alerts when a numbered listing is removed", async () => {
+  await read("/sample-page", { text: "Rentals\nListing 101 · 2 bed\nListing 102 · 2 bed" });
+  const monitor = await read<Monitor>(
+    "/monitors",
+    { title: "Rentals", url: "sample://availability", condition: "change", intervalMinutes: 1 },
+    201,
+  );
+  await server.agent.worker.tick();
+  await read("/sample-page", { text: "Rentals\nListing 102 · 2 bed" });
+  await read(`/monitors/${monitor.id}/control`, { action: "check" });
+  await server.agent.worker.tick();
+  const alerts = (await read<AgentNotification[]>("/notifications")).filter(
+    (item) => item.taskId === monitor.taskId,
+  );
+  assert.equal(alerts.length, 1, "a removed listing is news");
+  assert.equal(
+    alerts[0]?.body,
+    "Changed at sample://availability\nRemoved:\n• Listing 101 · 2 bed",
+  );
+  await read(`/monitors/${monitor.id}/control`, { action: "stop" });
+});
+
+test("a change watch alerts on a change past the saved lines", async () => {
+  const long = "x".repeat(300);
+  const many = Array.from({ length: 2000 }, (_, i) => `Row ${i}`).join("\n");
+  for (const [before, after] of [
+    [`Terms\n${long} version 1`, `Terms\n${long} version 2`],
+    [`${many}\nLast row: open`, `${many}\nLast row: closed`],
+  ]) {
+    await read("/sample-page", { text: before });
+    const monitor = await read<Monitor>(
+      "/monitors",
+      { title: "Long page", url: "sample://availability", condition: "change", intervalMinutes: 1 },
+      201,
+    );
+    await server.agent.worker.tick();
+    await read("/sample-page", { text: after });
+    await read(`/monitors/${monitor.id}/control`, { action: "check" });
+    await server.agent.worker.tick();
+    const alerts = (await read<AgentNotification[]>("/notifications")).filter(
+      (item) => item.taskId === monitor.taskId,
+    );
+    assert.equal(alerts.length, 1, "a change past the saved lines is still news");
+    assert.match(alerts[0]?.body ?? "", /^Condition met at sample:\/\/availability: /);
+    await read(`/monitors/${monitor.id}/control`, { action: "stop" });
+  }
+});
diff --git a/tests/page-diff.test.ts b/tests/page-diff.test.ts
new file mode 100644
index 00000000..10d04a4b
--- /dev/null
+++ b/tests/page-diff.test.ts
@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  countPageDiff,
+  describePageDiff,
+  diffPage,
+  pageLines,
+  withoutRelativeTimes,
+} from "../apps/server/src/engine/page-diff.ts";
+
+test("page lines are trimmed, collapsed, deduplicated and bounded", () => {
+  assert.deepEqual(pageLines("  Jobs \n\n Siemens   AI\r\nSiemens AI\n"), ["Jobs", "Siemens AI"]);
+  assert.equal(pageLines("a\nb\nc", 2).length, 2);
+  assert.equal(pageLines("x".repeat(500))[0].length, 300);
+});
+
+test("new lines are separated from lines where a number changed", () => {
+  const before = [
+    "AI jobs in Munich",
+    "Siemens · Werkstudent AI · 2 openings · posted 1 day ago",
+    "BCG · Intern",
+  ];
+  const after = [
+    "AI jobs in Munich",
+    "SAP · Working Student AI Engineer",
+    "Siemens · Werkstudent AI · 3 openings · posted 2 days ago",
+  ];
+  assert.deepEqual(diffPage(before, after), {
+    added: ["SAP · Working Student AI Engineer"],
+    updated: ["Siemens · Werkstudent AI · 3 openings · posted 2 days ago"],
+    removed: ["BCG · Intern"],
+  });
+  assert.deepEqual(diffPage(before, before), { added: [], updated: [], removed: [] });
+});
+
+test("price, stock, count and version changes are updates", () => {
+  for (const [before, after] of [
+    ["Price: $399.99", "Price: $279.99"],
+    ["Only 3 left", "Only 0 left"],
+    ["Tickets available: 12", "Tickets available: 0"],
+    ["Latest release 1.2.3", "Latest release 2.0.0"],
+    ["1 comment", "2 comments"],
+  ]) {
+    const diff = diffPage(["Shop", before], ["Shop", after]);
+    assert.deepEqual(diff, { added: [], updated: [after], removed: [] }, before);
+  }
+});
+
+test("a removed numbered line is reported even when a similar line remains", () => {
+  assert.deepEqual(
+    diffPage(["Listing 101 · 2 bed", "Listing 102 · 2 bed"], ["Listing 102 · 2 bed"]),
+    { added: [], updated: [], removed: ["Listing 101 · 2 bed"] },
+  );
+  assert.deepEqual(diffPage(["1. Apple", "2. Banana", "3. Cherry"], ["1. Apple", "2. Cherry"]), {
+    added: [],
+    updated: ["2. Cherry"],
+    removed: ["2. Banana"],
+  });
+});
+
+test("the change summary lists sections, clips long lists, and counts lines", () => {
+  const diff = {
+    added: Array.from({ length: 10 }, (_, i) => `Role ${i}`),
+    updated: ["Price $12"],
+    removed: [],
+  };
+  const text = describePageDiff(diff);
+  assert.match(text, /^New:\n• Role 0\n/);
+  assert.match(text, /\+2 more\nUpdated:\n• Price \$12$/);
+  assert.doesNotMatch(text, /Removed/);
+  assert.equal(countPageDiff(diff), "11 lines changed (10 new, 1 updated)");
+  assert.equal(countPageDiff({ added: ["a"], updated: [], removed: [] }), "1 line changed (1 new)");
+  assert.equal(describePageDiff({ added: [], updated: [], removed: [] }), "");
+  assert.equal(countPageDiff({ added: [], updated: [], removed: [] }), "");
+});
+
+test("lines where only a relative time changed are left out", () => {
+  const before = [
+    "3 points by ada 58 minutes ago | hide",
+    "Vor 2 Stunden veröffentlicht",
+    "Show HN: A new tool",
+  ];
+  const after = [
+    "3 points by ada 1 hour ago | hide",
+    "Vor einer Stunde veröffentlicht",
+    "Show HN: A new tool",
+  ];
+  assert.deepEqual(diffPage(before, after), { added: [], updated: [], removed: [] });
+  assert.deepEqual(diffPage(before, ["4 points by ada 1 hour ago | hide", ...after.slice(1)]), {
+    added: [],
+    updated: ["4 points by ada 1 hour ago | hide"],
+    removed: [],
+  });
+});
+
+test("only relative times are blanked out of the page text", () => {
+  const page = (time: string, price: string) => `Posted ${time} · Price ${price}`;
+  assert.equal(
+    withoutRelativeTimes(page("58 minutes ago", "$399")),
+    withoutRelativeTimes(page("1 hour ago", "$399")),
+  );
+  assert.notEqual(
+    withoutRelativeTimes(page("1 hour ago", "$399")),
+    withoutRelativeTimes(page("1 hour ago", "$279")),
+  );
+});