Scheduler Monitor Mode

Turn any scheduled job into a change-aware monitor — wake only when a watched source changed, and hand the agent only the diff.

State persistence is now wired (PR #4057). JobStateStoreProtocol has a concrete ConfigYamlScheduleStore implementation (16 KiB per-job cap), and ScheduledAgentExecutor loads prior state into a “Notepad” prompt block, threads it into state=-aware gates, and persists GateResult.state_updates + agent-emitted state — including on no_change / skip ticks. See Cross-Run Memory for the full walkthrough. The change-detection probe + hash + diff wrapper (what actually decides a source changed) still ships in a follow-up.

Quick Start

Agent-centric — watch a page, tell me only what's new

The agent schedules the monitor for you from a plain request.

from praisonaiagents import Agent
from praisonaiagents.tools import schedule_add

agent = Agent(name="watcher", tools=[schedule_add])
agent.start(
    "Every hour, monitor https://status.example. Only tell me when it changes, "
    "and tell me only what's new."
)

Direct Python — build the ScheduleJob yourself

Set monitor to name a cheap source to probe each tick.

from praisonaiagents.scheduler import ScheduleJob, parse_schedule

job = ScheduleJob(
    name="site-watch",
    message="The watched page changed. Here is the diff; summarise what is new.",
    schedule=parse_schedule("weekdays at 9am"),   # natural language also works
    monitor={"url": "https://status.example"},   # or {"command": "..."}
)

Shell source — probe a cheap counter

A bounded command is a better source than a full HTML page.

job = ScheduleJob(
    name="unread-watch",
    message="Unread count changed — summarise what is new.",
    schedule=parse_schedule("every 1h"),
    monitor={"command": "curl -s https://api.example/unread | jq '.count'"},
)

YAML — configure via agents.yaml

schedule:
  every: "1h"
  message: "Summarise what is new."
  monitor:
    url: "https://status.example"
  deliver: "telegram:123456"

How It Works

The wrapper hashes the probed source and compares it to the last-seen hash held in per-job state. Caller contract (verbatim from the SDK): “Because a legacy stateless gate accepts only job, callers MUST NOT unconditionally pass state=. Detect capability first — e.g. call should_run(job, state=prior) only when the gate opts into state, otherwise fall back to should_run(job) — so stateless gates keep working unchanged and never raise TypeError.” An error probe (a transient 500) leaves prior state untouched, so a later recovery to the prior output still suppresses — a transient failure does not count as a change.

Run Status: `no_change` vs the others

RunRecord.status gains a fourth value so an operator can tell a silent monitor apart from a deliberate skip.

`status`	Meaning	Tokens	Delivery
`succeeded`	The model turn ran and finished	Yes	Yes
`failed`	The run errored	Maybe	On-failure only
`skipped`	A go/no-go gate said “don’t run”	No	No
`no_change`	A watched source was unchanged since the last tick	No	No

no_change implies run=False — the core enforces this invariant in GateResult.__post_init__. Use no_change records in session show to prove a monitor is running even when it is silent.

What’s Stored in Per-Job State

The monitor keeps a small durable scratchpad keyed by job id — typically the last-seen hash, plus an optional cursor / watermark.

from typing import Any, Dict, Protocol, runtime_checkable

@runtime_checkable
class JobStateStoreProtocol(Protocol):
    """Bounded per-job durable scratchpad. All methods OPTIONAL — callers use hasattr()."""

    def get_state(self, job_id: str) -> Dict[str, Any]: ...
    def set_state(self, job_id: str, state: Dict[str, Any]) -> None: ...  # size-capped
    def clear_state(self, job_id: str) -> None: ...  # called when a job is removed

The state is bounded (size-capped by the implementation) and cleared when the job is removed. The core owns only the shape; the wrapper decides where to persist it.

Distinct From Other Gates

Pick the right sibling — monitor is the stateful one that seeds a diff.

Field	Stateful?	Seeds	Distinct outcome
`pre_run`	No	Whole gate output	`skipped`
`monitor`	Yes	A bounded diff	`no_change`
`command`	No	Nothing (no LLM)	model-free action

Configuration Options

The monitor field is a small mapping naming one cheap source to probe each tick.

Key	Type	Description
`command`	`str`	A shell command whose stdout is hashed and diffed
`url`	`str`	A bounded fetch whose body is hashed and diffed

monitor={"url": "https://status.example"}
# or
monitor={"command": "curl -s https://api.example/unread | jq '.count'"}

monitor serialises only when set — None (default) keeps the existing stateless behaviour, and an explicitly-empty mapping round-trips faithfully. For the full field types, see the auto-generated SDK reference rather than duplicating them here.

Best Practices

Prefer a bounded, cheap probe

A JSON endpoint returning a single counter beats hashing a full HTML page — it changes only when the thing you care about changes, and it is fast on every tick.

# Good — a small, stable signal
monitor={"command": "curl -s https://api.example/unread | jq '.count'"}

# Avoid — a whole page churns on ads, timestamps, and markup noise
monitor={"url": "https://example.com/full-homepage"}

A transient error is not a change

An error probe leaves prior state untouched — a transient 500 does not “count as a change”. When the source recovers to its prior output, the tick still suppresses. Design probes that fail loudly (non-zero exit) rather than emitting an error page as “content”.

Use no_change records to prove a monitor is alive

A silent monitor looks identical to a broken one. Check run history — a stream of no_change records proves the monitor is probing every tick and simply has nothing to report.

praisonai session show   # look for no_change entries

Never pass state= to a stateless gate

Callers MUST detect capability first. Pass state= only when the gate opts into state; otherwise fall back to should_run(job) so legacy stateless gates never raise TypeError.

Scheduler Cross-Run Memory

The notepad that persists state across runs — now wired

Scheduler Pre-Run Gate

The stateless sibling — a cheap go/no-go gate

Scheduler Command Action

The no-LLM sibling — deliver a command’s stdout verbatim

Scheduler Delivery

Where results go — note no_change ticks do not deliver

Async Agent Scheduler

The scheduler this monitor plugs into

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Scheduler Monitor Mode

Quick Start

How It Works

Run Status: `no_change` vs the others

What’s Stored in Per-Job State

Distinct From Other Gates

Configuration Options

Best Practices

See Also

Scheduler Cross-Run Memory

Scheduler Pre-Run Gate

Scheduler Command Action

Scheduler Delivery

Async Agent Scheduler

​Quick Start

​How It Works

​Run Status: no_change vs the others

​What’s Stored in Per-Job State

​Distinct From Other Gates

​Configuration Options

​Best Practices

​See Also

​Related

Scheduler Cross-Run Memory

Scheduler Pre-Run Gate

Scheduler Command Action

Scheduler Delivery

Async Agent Scheduler

Quick Start

How It Works

Run Status: `no_change` vs the others

What’s Stored in Per-Job State

Distinct From Other Gates

Configuration Options

Best Practices

See Also

Related