Skip to content

App events never reach an agent: add daemon-side retention and a pull surface for app_event #6

Closed

Description

@V3RON

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 event wire frame (docs/PROTOCOL.md §4) and its guard isEventMessage.
  • The daemon mapping it to the app_event event kind, delivered over events.subscribe (docs/ARCHITECTURE.md §5).
  • cordierite events [selector] --follow, which streams it as NDJSON (packages/cordierite/src/commands/events.ts).

What's missing:

  1. No MCP surface. packages/cordierite/src/mcp/server.ts subscribes to daemon events only to drive notifications/tools/list_changed — see LIST_CHANGE_EVENT_KINDS, which deliberately excludes app_event. An MCP client has no way to observe app events at all.
  2. No retention. createEventBus (packages/cordierite/src/daemon/event-bus.ts) is pure synchronous fan-out over a Set of 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 with tool_timeout. Mirrors cordierite_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 mcp is 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 and docs/ARCHITECTURE.md §5 need updating for the new RPC method and the cursor/sequence field on EventNotification.
  • 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.
  • createEventBus already takes a Clock seam, so the buffer and cursor semantics are unit-testable with no daemon, no socket, and no device.

Related

Activity

  1. changed the title [-]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`[/+] on Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions