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 id is 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), and actions[] — 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.

MCP (headless agents — preferred)

Tool ic_events_next. Args (all optional):

{
  "name": "ic_events_next",
  "arguments": {
    "since": 412,            // your last-seen event id. Omit / 0 = full backlog (capped at limit).
    "types": ["inbox_envelope", "tier_requested"],  // optional filter; omit = all entitled types
    "limit": 50              // default 50, max 500
  }
}

The MCP call wraps the result: { "ok": true, "events": [...], "cursor": <int>, "has_more": <bool>, "as_of": "<ISO>" }. Unknown strings in types are dropped silently — no error.