Monitors (change monitors)

🔵 A monitor is a pull trigger: it watches an external source and starts an agent run only when new items appear (unlike cron, which fires on a schedule regardless). The file is config/monitors.yaml, read at startup.

monitors:
  - name: news-watch
    source:
      type: rss
      url: "https://lenta.ru/rss"
    template: rss-agent
    prompt: "Кратко резюмируй эти новые статьи:\n{{items}}"
    notify: [{ type: telegram, chat_id: 123456 }]
    poll_secs: 300

Field	Meaning
`name`	unique id (also the cursor key and the `monitor:<name>` session)
`source.type`	source of changes: `rss`, `yandex_disk`, or `plugin`
`source.url`	feed URL (for `rss`)
`source.token_file`	Yandex refresh token file (for `yandex_disk`; written by the `yandex_tool` login)
`source.client_id` / `source.client_id_env`	OAuth client id or env variable name (for `yandex_disk`)
`source.client_secret` / `source.client_secret_env`	OAuth client secret or env variable name (for `yandex_disk`)
`source.path`	Disk folder to watch, `/` by default (for `yandex_disk`)
`source.limit`	maximum records per poll, 50 by default (for `yandex_disk`)
`source.kind` / `source.config`	kind and config of the native source (for `plugin`, see Native plugins)
`template`	agent template to run on new items
`prompt`	prompt template; `{{items}}` is replaced with the new items
`notify`	result sinks (same types as cron, see Cron)
`poll_secs`	poll interval, minimum 10 (default 300)

Cursor. The monitor stores its position in logs/monitors.db. The first poll only "catches up" (saves the cursor, starts nothing); after that, the agent starts only on items newer than the cursor. The run happens in the monitor:<name> session, so budgets, hooks, tools, and the event store behave as in a normal run.

Sources. Built-in ones are rss and yandex_disk. A native plugin can add its own source.type via type: plugin + kind (see Native plugins).

Yandex.Disk

yandex_disk triggers when files appear or change in the folder. A refresh token saved by logging in to Yandex is required (the same token_file as for yandex_tool). The cursor is the freshest modified label; each poll returns everything changed later, newest first.

monitors:
  - name: yandex-disk-watch
    source:
      type: yandex_disk
      token_file: data/yandex-oauth/disk_token.json
      client_id_env: YANDEX_OAUTH_CLIENT_ID
      client_secret_env: YANDEX_OAUTH_CLIENT_SECRET
      path: "/"
      limit: 50
    template: yandex-agent
    prompt: "На Яндекс.Диске появились новые/изменённые файлы:\n{{items}}\nКратко опиши их."
    poll_secs: 300

Monitors are one way to subscribe to events; the others are in Event subscriptions.