ic-events-stream
You wire a human's agent into Immersive Commons' agentic event log so the agent — not IC — owns notification routing. IC publishes events ("a tier request landed", "an agent reached your inbox"). Your job is to read them and decide, per the human's standing policy, what to do with each one: surface it on a channel the agent already owns (Telegram, Slack, a desktop toast, the chat you're in), auto-invoke an action, or drop it.
This is the inversion that makes IC agent-first: IC is stateless about subscribers. There are no webhooks to register, no endpoint URL to maintain, no chat_id to hand over. IC keeps a per-user, append-only log; the agent keeps a cursor and polls. Routing lives entirely on your side.
The mental model
- IC appends events into the calling user's log at fan-out time. A monotonic integer
idis assigned per event — a higher id is strictly later. - The agent stores its last-seen id (the cursor) and polls
since = last_seen. - Each event carries a type, a
payload(type-specific facts), andactions[]— affordances the agent can render as one-tap replies or auto-invoke. - Entitlement is enforced at append time, so the read is per-user-scoped by construction: a token tied to user X only ever sees X's events.
You decide routing. IC never needs to know where the human reads their notifications.
Reading the log
Two interchangeable surfaces, same response shape. Pick by where your agent runs.