Skip to content

A personal agent with a browser, terminal, files, and work that keeps going built with CopilotKit and AG-UI.

TypeScript

feature: show what changed when a watched page changes (#66)

Asem ahmed2a68bb60d2c1
diff --git a/apps/server/src/engine/page-diff.ts b/apps/server/src/engine/page-diff.ts
new file mode 100644
index 0000000..b516473
--- /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 9f8f24a..e0b2ff2 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 {
@@ -1087,7 +1096,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
@@ -1111,6 +1136,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",
@@ -1118,13 +1150,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,
@@ -1137,7 +1172,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 953f77e..bf4c86f 100644
--- a/tests/agent-api.test.ts
+++ b/tests/agent-api.test.ts
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { after, before, test } from "node:test";
+import { after, before, beforeEach, test } from "node:test";
import { CopilotKitIntelligence } from "@copilotkit/runtime/v2";
import { createApp } from "../apps/server/src/app.ts";
import type { Config } from "../apps/server/src/config.ts";
@@ -55,6 +55,12 @@ before(async () => {
assert.equal(session.status, 200);
token = (await session.json()).token;
});
+beforeEach(async () => {
+ // Keep persisted fixtures and the session, but give each independent test its
+ // own app middleware state, including the per-connection request budget.
+ await server.agent.stop();
+ server = await createApp(db, config);
+});
after(async () => {
await server?.agent?.stop();
await db?.close();
@@ -449,3 +455,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 0000000..10d04a4
--- /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")),
+ );
+});