Filter app events by name glob and bound payloads on every surface

[V3RON]

Lands after #93, which leaves the retention buffer, appduct_events, appduct_wait_for_event and appduct events carrying app events only. Everything below assumes that: an event is { name, payload, ts, seq, sessionId, alias } and kinds no longer exists on any agent- or user-facing surface. The RPC's events.subscribe keeps kinds for the daemon's own consumers, such as the wait for session_claimed behind appduct_wait_for_session.

Why

An app that posts events often makes the current surface expensive for an agent:

• appduct_events filters by kind only. To find checkout_completed among two hundred app events, the agent drains all of them into its context and scans. One call can return the whole 256-event buffer, each payload up to the 256 KiB wire limit, with no cap.
• appduct_wait_for_event targets one exact name and a shallow payload match; the client SDK has a predicate function instead. Two filtering models for one concept.
• A since cursor that fell off the buffer returns whatever is left with no signal that anything was evicted, and a limit-truncated page gives no hint whether to page again.
• appduct events has no filter at all, although events.subscribe already accepts one per connection (packages/appduct/src/daemon/daemon.ts:519).
• The shipped skill never mentions appduct_events or appduct_wait_for_event, so agents do not know the tools exist or how to loop on the cursor.

Expected outcome

One filter, by name, applied in the daemon on both the drain (events.since) and the live subscription (events.subscribe), plus a payload cap and two counters, exposed the same way on every surface.

name, a whole-name, case-sensitive pattern where * matches any run of characters and a pattern without * is an exact name. cart.* matches cart.item_added; *_failed matches checkout_failed.

• appduct_events({ selector?, since?, name?, limit?, payloadMaxBytes? }), limit defaulting to 50 like appduct_list_tools.
• appduct_wait_for_event({ selector?, name, since?, timeoutMs?, payloadMaxBytes? }). name stays required; * waits for the next app event of any name. The match object is removed.
• appduct events tail [selector] [--name <glob>] [--payload-max-bytes <n>] and appduct events since [selector] <cursor> [--name <glob>] [--payload-max-bytes <n>], both flags on both verbs.
• appduct/client: events({ name?, since?, limit?, payloadMaxBytes? }) and waitForEvent(name, { since?, timeoutMs?, payloadMaxBytes? }). The match predicate is removed.

payloadMaxBytes, per event. A payload whose JSON exceeds it is replaced by payloadPreview (the first payloadMaxBytes characters of that JSON) with truncated: true and payloadBytes: n on the event; otherwise payload is untouched. It is a param on both events.since and events.subscribe, so live events (the wait tool's live phase, appduct events without --since) are capped by the daemon too. The two MCP tools default it to 4096; the RPC params, the CLI flag and the SDK have no default. The full payload comes back with since: seq - 1, limit: 1 and a larger cap.

dropped: n on every events.since result: the number of events between since and the oldest retained one, 0 when nothing was evicted. appduct_wait_for_event reports it the same way when its drain phase crossed a gap.

remaining: n on every events.since result: matching events after the returned page, so an agent pages only while it is above 0. The trailing cursor line that events since prints becomes { cursor, dropped, remaining } under --json and cursor: 12, dropped: 0, remaining: 40 otherwise.

The shipped skill teaches two patterns: after a call that triggers async work, drain with appduct_events and a name glob, keep the cursor, page while remaining > 0, treat dropped > 0 as a gap; for an expected outcome, appduct_wait_for_event with since and a long timeoutMs, which Claude Code moves to a background task after two minutes and reports as a task notification. The CLI reference table gains the new flags.

Constraints and non-goals

• No change to the app-to-daemon wire protocol. Event names stay unconstrained on the wire; a literal * in a name cannot be matched exactly, and the writing-tools guidance recommends [a-z0-9_.] names.
• The RPC change is additive apart from removing match. events.since loses kinds in Log Appduct's own event kinds to a file instead of showing them to agents #93; events.subscribe keeps it for internal consumers.
• Non-goal: payload predicates of any kind, on any surface. The SDK's predicate goes; a test that needs one loops on waitForEvent with since or filters events() itself.
• Non-goal: waiting on several names in one call beyond what a glob expresses.
• Non-goal: an event catalog (apps declaring the events they post). Separate design.

How we know it is done

1. events.since with name: "cart.*" returns only events whose name matches; name: "checkout_completed" never matches checkout_completed_v2; matching is case-sensitive.
2. events.subscribe with name delivers only matching live events on that connection.
3. appduct_events with no limit returns at most 50 events and a cursor that pages forward.
4. An event whose payload JSON is longer than payloadMaxBytes comes back with payloadPreview, truncated: true and payloadBytes, and no payload; a smaller one comes back unchanged. appduct_events and appduct_wait_for_event apply 4096 by default; appduct events tail --json, appduct events since --json and app.events() do not truncate unless told to.
5. After more than eventBufferSize app events, events.since with the original cursor reports dropped equal to the number evicted, and dropped: 0 otherwise.
6. remaining equals the number of matching events after the returned page and is 0 on the last page.
7. appduct_wait_for_event rejects match as an unknown parameter and resolves on name: "*" for the next app event.
8. appduct events tail --name '*_failed' --json and appduct events since 0 --name '*_failed' --json print only matching NDJSON lines, and the events since cursor line carries dropped and remaining.
9. app.waitForEvent("cart.*") resolves on cart.item_added; WaitForEventOptions has no match.
10. The shipped skill describes the drain loop and the background wait, and the CLI reference lists the new flags under events tail and events since.

Alternatives considered

• A match object with dot-path keys over name and payload: rejected, one filter by name is enough and easier to teach.
• Truncating in the MCP server only: rejected, the daemon param serves CLI, SDK and MCP from one implementation.
• oldestSeq instead of dropped: rejected, agents would have to do the subtraction.

Slices

Work these in order (design):

• Filter app events by name glob in the daemon and appduct_events #112
• Report dropped and remaining events and cap payload size #113
• Unify the event wait on a name glob for MCP and the SDK #114
• Add --name and --payload-max-bytes to appduct events tail and since #115
• Teach the drain loop and background wait in the shipped skill #116

[V3RON]

#96 is accepted and ready. It moves the CLI to appduct <noun> <verb> as a clean break, with no aliases. appduct events becomes appduct events tail [selector] for the live stream and appduct events since [selector] <cursor> for the one-shot pull. The --since flag is gone.

Please update this issue's CLI parts to match:

• In Expected outcome, replace appduct events [selector] [--name <glob>] [--payload-max-bytes <n>] [--since <cursor>] with appduct events tail [selector] [--name <glob>] [--payload-max-bytes <n>] and appduct events since [selector] <cursor> [--name <glob>] [--payload-max-bytes <n>]. Both flags go on both verbs.
• "The CLI's trailing cursor line" is the one events since prints.
• Criterion 4: appduct events --json becomes appduct events tail --json and appduct events since --json.
• Criterion 8 becomes: "appduct events tail --name '*_failed' --json and appduct events since 0 --name '*_failed' --json print only matching NDJSON lines, and the events since cursor line carries dropped and remaining."
• Criterion 10: the CLI reference table lists the new flags under events tail and events since.

---

Generated by Claude Code

[V3RON]

Question: approve this design?

Design

Premise. #93 has landed (#97, #98). #96 is in draft PR #111, so the CLI slice waits for it. The code forces two changes to the plan:

• seq counts every session event, including the kinds that are never retained, so dropped can't be worked out from seqs. From now on, seq counts app events only and other kinds carry 0. Then dropped = max(0, oldest.seq - since - 1). Nothing reads seq on non-app events.
• The daemon keeps one events.subscribe filter per connection, and each call replaces it. The SDK runs every waitForEvent on one shared connection, so concurrent waits would clobber each other's name. Each wait will open its own stream, as the MCP tool already does.

Wording fix: payloadMaxBytes counts UTF-8 bytes. payloadPreview is the longest prefix of the JSON that fits in that many bytes, without splitting a code point.

Goal. Agents, scripts and tests pull or wait for app events by a name glob. Pages and payloads are bounded, and every pull reports how many events were evicted and how many remain.

Shape.

• daemon/event-bus.ts: since(sessionId, { since?, limit?, name?, payloadMaxBytes? }) → { events, cursor, dropped, remaining }. The subscribe fan-out in daemon.ts also goes through projectAppEvent(event, { name?, payloadMaxBytes? }). That gives the glob and the truncation one implementation with two callers. All calls, no new events or ports.
• @appduct/shared:
  • EventsSinceParams and EventsSubscribeParams gain name? and payloadMaxBytes?.
  • EventsSinceResult gains dropped and remaining.
  • App-event data becomes { name, payload } | { name, payloadPreview, truncated: true, payloadBytes }.
  • AppEvent and toAppEvent() move here, so the SDK and MCP return the same flat event.
• New module packages/appduct/src/events/: waitForAppEvent(stream, { sessionId, name, since?, timeoutMs, payloadMaxBytes? }) → Promise<{ event: AppEvent; dropped: number }>. It replaces the duplicated drain-then-live code in mcp/events-tool.ts and client/app-client.ts.
• CLI: events tail and events since pass --name and --payload-max-bytes through to the RPC.

Not in scope. The issue's non-goals, and dropped on the SDK's waitForEvent (the issue asks for it on the MCP tool only).

Slices.

1. Name glob, end to end through appduct_events.
   1. events.since with name: "cart.*" returns only matching events. checkout_completed never matches checkout_completed_v2, and matching is case-sensitive.
   2. events.subscribe with name delivers only matching live events on that connection.
   3. appduct_events accepts name, defaults limit to 50, returns flat events, and its cursor pages forward.
2. Bounded pages. Makes seq app-only. Adds dropped, remaining and payloadMaxBytes on events.since and events.subscribe, surfaced in appduct_events (default cap 4096) and app.events() (no default). Covers the issue's criteria 4, 5 and 6 for these surfaces.
3. One wait. Adds waitForAppEvent. appduct_wait_for_event and app.waitForEvent move onto it: glob name, no match, payloadMaxBytes (4096 for MCP, none for the SDK), and dropped on the MCP result. Covers criteria 4, 7 and 9, plus: two concurrent waitForEvent calls with different names on one client each resolve.
4. CLI flags (after feat(cli): unify the CLI as noun-verb commands (#96) #111). Covers criteria 4 and 8.
5. Shipped skill. Covers criterion 10.

Each slice updates its own docs and CHANGELOG.md.

Decisions (2026-09-25):

• app.events() and app.waitForEvent() are overloaded. With no payloadMaxBytes they return FullAppEvent<T> (payload: T), so existing e.payload code compiles unchanged. With payloadMaxBytes they return the AppEvent<T> union, and the caller narrows on truncated. This lands in slices 2 (events()) and 3 (waitForEvent()).
• appduct_events returns flat events instead of the kind/data envelope. The break for anything parsing today's output is accepted.