fix(tasks): plan page and news watches as important-changes checks

CHANGELOG.md

@@ -24,7 +24,8 @@ and versions follow [Semantic Versioning](https://semver.org/).
   important changes**. Each check is compared with the last one without any AI, so an unchanged page costs nothing
   and stays silent; only when something changed does your fast AI model decide whether it matters, and then you get
   one notification that says what changed. Every watch also keeps a quiet list of its recent checks ("Checked,
-  nothing new", "Something changed. You were told") under Runs.
+  nothing new", "Something changed. You were told") under Runs. When you ask Sentient to watch a page, a feed or the
+  news, it now uses this kind of check by default, so a view counter or a new timestamp no longer sends you a message.
 - **Fuzzy times for repeating tasks:** a daily or weekly task can run "in the morning", "afternoon", "evening" or "at
   night" instead of at an exact time; Sentient picks a time inside that part of the day. Say it in your request
   ("every weekday morning") or pick it in the schedule editor.

docs/API.md

@@ -1910,6 +1910,9 @@ A device ("node") is a phone, a pair of smart glasses, a watch, or the desktop a
   `script` (and a `schedule`, e.g. `interval`) to its reply. The code must use `from sentient_tools import tools, result` and
   read-only tools; it is checked with `ast.parse`, the planner gets one chance to fix code that does not compile, then
   planning fails with a readable `error`. A script job the planner leaves on an immediate one-off schedule becomes `interval` 60.
+  A `changed` script the planner proposes that reads a page, a feed or the news (`web_fetch`, `news_search`,
+  `news_top_headlines`, `browser_open`, `browser_snapshot`, `browser_extract`) is stored as `noteworthy`, unless the
+  task's script was already `changed` (#298). Imported Hermes monitor jobs keep `changed`.
 - `POST /api/tasks/{id}/script/test` → SandboxResult (does not change `last_result`); see section 4.
 
 ### Wake word and talk mode (owner: voice)

sentient/tasks/prompts.py

@@ -183,8 +183,8 @@
     - Use only the Python standard library. Keep it short, and handle missing keys so the script does not crash.
     - The script runs once per check and Sentient runs it again on the schedule: never loop, wait or sleep inside it. For "changed" and "noteworthy", Sentient remembers the last result and compares for you: just return the current value, never store or compare it yourself.
     - `"condition": "alert"`: finish with `result({{"alert": True, "message": "What the user should know"}})` when the condition is met, otherwise `result({{"alert": False}})`.
-    - `"condition": "changed"`: finish with `result(value)` where `value` is the small thing being watched (a price, a status, a list of titles); the job acts when it differs from the previous check.
-    - `"condition": "noteworthy"`: like "changed", but when the value differs a small AI check decides whether the change matters before acting. Prefer it for pages, news or lists where small changes (times, counters, ads) are noise.
+    - `"condition": "noteworthy"`: finish with `result(value)` where `value` is what is being watched; when it differs from the previous check, a small AI check decides whether the change matters before acting. This is the default for watching a page, a feed or the news ("watch this page", "tell me about new posts"), where small changes (times, counters, ads) are noise.
+    - `"condition": "changed"`: like "noteworthy" with no AI check: the job acts on any difference. Use it only for one exact value (a price, a status).
     - `"condition": "every_run"`: finish with `result(value)` or print the report; the job acts after every check that produced something, even when it is the same as last time. Use it only when the user wants a report on every run.
     - `"then": "notify"` sends the alert message to the user. `"then": "run"` starts a normal run of your `plan` each time the condition fires, with the script result as its context; use it when real work must follow (writing, summarizing, sending).
     - If the schedule above is not already recurring or triggered, also return a `schedule`, for example {{"type": "recurring", "frequency": "interval", "interval_minutes": 60}} for "every hour" (minimum 5 minutes), or a daily/weekly schedule.
@@ -209,7 +209,7 @@
 }}
 
 For a watch job (directive 10) add these keys to the same object:
-  "script": {{"code": "from sentient_tools import tools, result\\n...", "condition": "alert, changed, noteworthy or every_run", "then": "notify or run"}},
+  "script": {{"code": "from sentient_tools import tools, result\\n...", "condition": "alert, noteworthy, changed or every_run", "then": "notify or run"}},
   "schedule": {{"type": "recurring", "frequency": "interval", "interval_minutes": 60}}
 Leave both keys out for every other task.
 

sentient/tasks/scripts.py

@@ -24,6 +24,10 @@
 CONDITIONS = ("alert", "changed", "noteworthy", "every_run")
 COMPARING = ("changed", "noteworthy")  # act on a difference from the last result
 THEN = ("notify", "run")
+# tools that read a page, a feed or the news: counters, times and ads change between checks (#298)
+PAGE_TOOLS = frozenset(
+    {"web_fetch", "news_search", "news_top_headlines", "browser_open", "browser_snapshot", "browser_extract"}
+)
 MAX_CODE_CHARS = 20000
 MAX_RESULT_CHARS = 20000
 REPORT_CHARS = 3000  # an every-run report shows this much of the script's output
@@ -84,6 +88,34 @@ def normalize_script(raw: Any, previous: dict | None = None) -> dict:
     return out
 
 
+def reads_pages(code: str) -> bool:
+    """True when the script calls a tool that reads a page, a feed or the news (``PAGE_TOOLS``)."""
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return False
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name) and node.value.id == "tools":
+            name = node.attr  # tools.web_fetch(...)
+        elif isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "call_tool" and node.args:
+            name = getattr(node.args[0], "value", None)  # call_tool("web_fetch", ...)
+        else:
+            continue
+        if isinstance(name, str) and name in PAGE_TOOLS:
+            return True
+    return False
+
+
+def planner_default(script: dict, previous: dict | None) -> dict:
+    """A ``changed`` check the planner proposes for a page, a feed or the news becomes ``noteworthy`` (#298): any
+    byte change there (a view counter, a timestamp) would notify. A check that was already ``changed`` stays so."""
+    if script.get("condition") != "changed" or (previous or {}).get("condition") == "changed":
+        return script
+    if not reads_pages(script.get("code") or ""):
+        return script
+    return {**script, "condition": "noteworthy"}
+
+
 def trigger_prelude(trigger_data: dict | None) -> str:
     """Lines prepended to the code of a triggered script so it can read the event as ``trigger_event``."""
     payload = json.dumps(trigger_data if isinstance(trigger_data, dict) else None, ensure_ascii=False, default=str)

sentient/tasks/service.py

@@ -1360,7 +1360,8 @@ async def _plan(self, task_id: str, *, auto_approve: bool = False) -> None:
         await self._notify(task, f"I've created a new plan for you: '{short}'", "Plan ready for approval", "approval_needed")
 
     async def _planned_script(self, task: dict, data: dict, system: str, parts: list[str]) -> tuple[dict | None, dict]:
-        """The check script the planner proposed (validated), else the task's existing one.
+        """The check script the planner proposed (validated), else the task's existing one. A page, feed or news
+        watch proposed as ``changed`` becomes ``noteworthy`` (``scripts.planner_default``).
 
         Code that does not compile gets one correction round; if it still does not compile,
         planning fails with a readable message (ScriptInvalid is a ValueError)."""
@@ -1369,7 +1370,7 @@ async def _planned_script(self, task: dict, data: dict, system: str, parts: list
         if not isinstance(raw, dict) or raw.get("code") is None:
             return previous, data
         try:
-            return normalize_script(raw, previous), data
+            return scripts.planner_default(normalize_script(raw, previous), previous), data
         except ScriptInvalid as exc:
             log.info("planner script for task %s rejected, asking for a fix: %s", task["id"], exc)
             retry = [*parts, (
@@ -1386,7 +1387,7 @@ async def _planned_script(self, task: dict, data: dict, system: str, parts: list
         raw = fixed.get("script")
         if not isinstance(raw, dict) or raw.get("code") is None:
             return previous, fixed
-        return normalize_script(raw, previous), fixed
+        return scripts.planner_default(normalize_script(raw, previous), previous), fixed
 
     # ------------------------------------------------------------------ swarm
     async def _orchestrate_swarm(self, task_id: str) -> None:

tests/tasks/test_scripts_triggers_retry.py

@@ -295,6 +295,50 @@ async def test_planner_produces_script_job(make_app):
     assert "approval_needed" in _events(await app.notifications.list(), task["task_id"])
 
 
+PAGE_CODE = (
+    "from sentient_tools import tools, result\n"
+    "page = tools.web_fetch(url='https://example.org/events')\n"
+    "result(page.get('content', ''))\n"
+)
+
+
+async def test_planner_defaults_page_watches_to_important_changes(make_app):
+    watch = {**PLAN_SCRIPT, "name": "New events", "description": "Tell me about new events on the page",
+             "script": {"code": PAGE_CODE, "condition": "changed", "then": "notify"}}
+    llm = FakeProvider(json_replies=[REFINE_ONCE, watch])
+    app = await make_app(llm)
+    task = await app.tasks.create_task("Watch this page and tell me about new events: https://example.org/events")
+    await app.tasks.drain()
+    task = await app.tasks.get(task["task_id"])
+    assert task["status"] == "approval_pending" and task["task_type"] == "script"
+    assert task["script"]["condition"] == "noteworthy" and task["script"]["code"] == PAGE_CODE
+    assert task["script"]["then"] == "notify"
+    prompt = json_calls(llm, "planner")[1]["messages"][0]["content"]
+    assert "This is the default for watching a page, a feed or the news" in prompt
+
+
+@pytest.mark.parametrize(
+    ("code", "condition", "previous", "expected"),
+    [
+        (PAGE_CODE, "changed", None, "noteworthy"),
+        ("from sentient_tools import tools, result\nresult(tools.news_search(query='rust'))", "changed", None,
+         "noteworthy"),
+        ("from sentient_tools import call_tool, result\nresult(call_tool('browser_extract'))", "changed", None,
+         "noteworthy"),
+        # one exact value, not a page: any change matters
+        ("from sentient_tools import tools, result\nresult(tools.internet_search(query='btc'))", "changed", None,
+         "changed"),
+        (PAGE_CODE, "alert", None, "alert"),
+        (PAGE_CODE, "every_run", None, "every_run"),
+        # a watch that is already on plain "changed" keeps it when it is planned again
+        (PAGE_CODE, "changed", {"code": PAGE_CODE, "condition": "changed"}, "changed"),
+    ],
+)
+def test_planner_default_only_moves_page_feed_and_news_watches(code, condition, previous, expected):
+    script = normalize_script({"code": code, "condition": condition}, previous)
+    assert scripts.planner_default(script, previous)["condition"] == expected
+
+
 async def test_planner_script_with_invalid_code_is_fixed_or_rejected(make_app):
     bad = {**PLAN_SCRIPT, "script": {**PLAN_SCRIPT["script"], "code": "def broken(:\n"}}
     llm = FakeProvider(json_replies=[REFINE_ONCE, bad, PLAN_SCRIPT, REFINE_ONCE, bad, bad])