Repository navigation
Description
Summary
postEvent() → app_event is fully implemented on the wire and on the control plane, but there is no way for an agent to consume it. The app can push, but only a human running cordierite events --follow can receive. This makes the "app pushes updates to the agent" direction effectively unavailable over MCP.
This issue covers the dependency-free core. The optional Claude Code channel transport is split out into #11.
Current state
What already exists:
postEvent(name, payload?)on the React Native client (packages/react-native/src/public-api.ts).- The
eventwire frame (docs/PROTOCOL.md§4) and its guardisEventMessage. - The daemon mapping it to the
app_eventevent kind, delivered overevents.subscribe(docs/ARCHITECTURE.md§5). cordierite events [selector] --follow, which streams it as NDJSON (packages/cordierite/src/commands/events.ts).
What's missing:
- No MCP surface.
packages/cordierite/src/mcp/server.tssubscribes to daemon events only to drivenotifications/tools/list_changed— seeLIST_CHANGE_EVENT_KINDS, which deliberately excludesapp_event. An MCP client has no way to observe app events at all. - No retention.
createEventBus(packages/cordierite/src/daemon/event-bus.ts) is pure synchronous fan-out over aSetof listeners with no buffer. Anything emitted while no one is subscribed is gone. An agent that calls a tool and then asks "what happened?" has already missed the answer — which is the shape of every agent interaction, since MCP is request/response.
Proposal
1. Per-session ring buffer in the daemon
Retain the last N events per session (config-driven, e.g. eventBufferSize, default ~256) with a monotonically increasing cursor per event. Terminal session states drop the buffer along with the alias. The existing fan-out path is untouched — this is retention added alongside it.
Cursor scope: per-session, matching the selector model used everywhere else in the RPC surface. Worth settling before the first line of code, since changing it later is awkward: a daemon-global cursor would make a future "drain every device at once" call trivial, but complicates the common single-session case and doesn't match how any other method here is addressed.
2. An events.since RPC method
So the MCP server stays a thin proxy, consistent with every other capability here. A cordierite events --since <cursor> CLI flag falls out of the same method for free, and makes the CLI useful in a non---follow scripted context for the first time.
3. Two built-in MCP tools
Alongside the existing cordierite_connect / cordierite_wait_for_session in packages/cordierite/src/mcp/connect-tool.ts:
cordierite_events({ selector?, since?, kinds?, limit? })— drain everything buffered since a cursor, returning the events plus the new cursor.cordierite_wait_for_event({ selector?, name, match?, timeoutMs })— block until a matching event arrives, or reject withtool_timeout. Mirrorscordierite_wait_for_session's existing semantics and implementation shape.
MCP is request/response, so this pull surface is what makes the feature work everywhere — in Codex, in CI, and in any client without a push mechanism. #11 is additive on top of it and can never be depended on.
Constraint on the blocking wait tool
Two Claude Code MCP timeout behaviors bound cordierite_wait_for_event (and cordierite_wait_for_session, which already exists):
- A tool call that sends no response and no progress notification for the idle window aborts with an error. That window is 30 minutes for stdio servers (
cordierite mcpis stdio) and 5 minutes for HTTP/SSE/WebSocket. A long block must emit periodic progress notifications to stay alive. - A call still running after two minutes is automatically moved to a background task (Claude Code v2.1.212+): the agent receives a task ID immediately and keeps working, with the result arriving as a task notification. Good news for blocking waits — the session isn't stalled — but the result may land well after the call, so the tool description should set that expectation.
Cap timeoutMs server-side below the idle window rather than trusting the caller.
Why this matters
Right now the agent loop is strictly pull: call a tool, get a result, guess whether anything else happened. Any app state change that isn't the direct return value of a tool call is invisible. With retention plus these two tools, an app can drive the agent — "navigation finished", "push notification arrived", "the request you triggered failed" — which is the premise of Cordierite being an agent view over a running app rather than a remote function-call bus.
Notes
docs/PROTOCOL.md§4 anddocs/ARCHITECTURE.md§5 need updating for the new RPC method and the cursor/sequence field onEventNotification.- Buffer memory is bounded per session and events are already size-capped by the 256 KiB frame limit, so retention shouldn't need byte accounting beyond the entry count.
createEventBusalready takes aClockseam, so the buffer and cursor semantics are unit-testable with no daemon, no socket, and no device.
Related
- Optional channel transport: push app events directly into a Claude Code session #11 — optional Claude Code channel transport, built on this. Preview-gated; deliberately not part of this issue.
- Ship a programmatic client so test runners can drive the app without shelling out to the CLI #8 — the programmatic client's
waitForEventdepends on this buffer. - Let apps declare read-only resources, not just tools (MCP
resources/read) #7 —notifications/resources/updatedrides the same event plumbing.
Activity
[-]App events never reach an agent: add daemon-side retention and an MCP surface for `app_event`[/-][+]App events never reach an agent: add daemon-side retention and a pull surface for `app_event`[/+]