Goal
Add first-class read cursors for event streams so Agent Feeds can answer questions like "what is new since last time?" without rereading or summarizing the whole stream history.
Why
Incoming sources such as email, SMS, blogs, notifications, and issue feeds need more than current-state search. Agents need a local way to distinguish unseen/new items from previously handled items while keeping state local and inspectable.
Proposed CLI surface
python3 scripts/agentfeeds.py streams changes <subscription-id> --json
python3 scripts/agentfeeds.py streams changes <subscription-id> --since <cursor|timestamp> --json
python3 scripts/agentfeeds.py streams mark-read <subscription-id>
python3 scripts/agentfeeds.py streams mark-read <subscription-id> --through <event-id|timestamp>
Design notes
- Keep cursors local under
~/.agentfeeds/; do not mutate fetched state payloads directly.
- Support event streams first; snapshots can return no changes or a single changed snapshot later.
- Include event id/time, subscription id, title, and compact snippets in
changes output.
- Preserve current
streams read behavior for full data reads.
- Make this agent-driven and token-efficient: agents should be able to check changes before reading full stream state.
Acceptance criteria
- Event streams can report new/unread events since the last mark-read.
- Agents can mark a stream read without editing state files manually.
- Cursor state survives sessions and is inspectable.
- Tests cover event streams with stable IDs, repeated fetches, and mark-read behavior.
Goal
Add first-class read cursors for event streams so Agent Feeds can answer questions like "what is new since last time?" without rereading or summarizing the whole stream history.
Why
Incoming sources such as email, SMS, blogs, notifications, and issue feeds need more than current-state search. Agents need a local way to distinguish unseen/new items from previously handled items while keeping state local and inspectable.
Proposed CLI surface
python3 scripts/agentfeeds.py streams changes <subscription-id> --jsonpython3 scripts/agentfeeds.py streams changes <subscription-id> --since <cursor|timestamp> --jsonpython3 scripts/agentfeeds.py streams mark-read <subscription-id>python3 scripts/agentfeeds.py streams mark-read <subscription-id> --through <event-id|timestamp>Design notes
~/.agentfeeds/; do not mutate fetched state payloads directly.changesoutput.streams readbehavior for full data reads.Acceptance criteria