Skip to content

Add event read cursors for incoming stream workflows #8

Description

@verkyyi

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions