Let apps declare the events they post, and let agents list them

[V3RON]

Builds on #93 (agents see app events only) and #94 (name glob filter on every surface).

Why

Tools are discoverable: an app registers each one with a description and schema, and an agent reads them with appduct tools or appduct_list_tools before calling anything. Events are not. An app posts them with postEvent(name, payload) and nothing tells the daemon which names exist or what their payloads look like. So an agent that wants to wait for an outcome has to guess the name for appduct_wait_for_event, read the app's source, or drain the buffer hoping the event already fired. docs/TOOLS.md tells app authors to postEvent("checkout_completed", { orderId }), yet the daemon cannot tell an agent that name exists.

Expected outcome

An app declares the events it posts, and agents list them the way they list tools.

App side. registerEvent({ name, description, payloadSchema? }) in React Native, Swift and Kotlin, returning a disposer, with the same lifecycle as registerTool: declared at any time while the app runs, removed on dispose, re-sent in full after a resume. payloadSchema follows the tool schema rules (Standard Schema or raw JSON Schema; the daemon never inspects it). Declaration is advisory: an undeclared postEvent still flows to agents. In development the SDK warns when a posted name is undeclared or its payload fails the declared schema; production posts as-is.

Wire and daemon. An event registry per session beside the tool registry, fed by an event_registry_snapshot / event_registry_delta pair with the same strict-validation-or-close rule as the tool registry, and an events.list RPC with the usual selector semantics. Registry changes emit an internal kind that goes to the log from #93, not to agents.

Agent surface. One new MCP tool, appduct_list_events({ selector?, name?, limit?, offset? }), returning one signature per declared event (checkout_completed { orderId: string } plus its description) with total. name takes #94's glob; an exact name that matches one declared event returns its full payload schema as well. CLI: appduct events --list [--name <glob>], same output as one signature line per event, or the full schema for an exact name. The shipped skill tells agents to list events before waiting on one, and the writing-tools reference tells app authors to declare each event they post.

Constraints and non-goals

• Declaration must not become an allowlist: every app using postEvent today keeps working unchanged. An SDK from before this change connects and works with no event registry.
• The daemon does not validate posted payloads against the declared schema.
• Non-goal: grouping events the way tools are grouped.
• Non-goal: a separate describe tool; the exact-name form of the list covers it.
• Non-goal: deriving a catalog from names already seen in the buffer.

How we know it is done

1. After registerEvent({ name: "checkout_completed", description: "...", payloadSchema }), events.list returns that event with its description and schema; after the disposer runs, it is gone.
2. appduct_list_events returns signature lines with total; with name: "cart.*" only matching events; with an exact name matching one event, that event's full payload schema.
3. appduct events --list prints one signature line per declared event, --name <glob> narrows it, and an exact name prints the full schema; --json carries the same data.
4. A session that resumes re-sends its event registry, and events.list matches the app's current declarations afterwards.
5. A postEvent with an undeclared name still reaches appduct_events; in development the SDK logs a warning naming the event.
6. An app built with an SDK that has no registerEvent connects and events.list returns an empty registry, no error.
7. Swift and Kotlin expose registerEvent with the same fields, and the conformance fixtures cover the snapshot and delta frames.
8. The shipped skill and docs/TOOLS.md describe declaring and listing events.

Alternatives considered

• Declare events on the tool that emits them (registerTool({ emits })): an event posted outside any tool has nowhere to be declared.
• A static list passed to connect(): cannot change while the app runs, does not fit code-split apps.
• Names seen so far in the retention buffer as the catalog: misses anything not fired yet and carries no description or schema.
• Allowlist like tools: breaks every existing postEvent caller until it declares.

Slices

Work in order. #126 and #127 can run in parallel.

• Declare events over the wire and list them with appduct events ls #124 Declare events over the wire and list them with appduct events ls
• Add appduct_list_events MCP tool #125 Add appduct_list_events MCP tool
• Add registerEvent to the Swift SDK #126 Add registerEvent to the Swift SDK
• Add registerEvent to the Kotlin SDK #127 Add registerEvent to the Kotlin SDK
• Add registerEvent to the React Native SDK #128 Add registerEvent to the React Native SDK

[V3RON]

Depends on the CLI shape decided in #96. If #96's design is approved before this is implemented, the CLI surface here becomes appduct events ls [selector] [--name <glob>] instead of appduct events --list, and criterion 3 changes accordingly. The MCP tool is unaffected.

[V3RON]

#96 is accepted and ready. It moves the CLI to appduct <noun> <verb> as a clean break, with no aliases, and it reserves appduct events ls for this catalog. Until this issue lands, events ls is a usage error.

Please update this issue's CLI parts to match:

• In Agent surface, appduct events --list [--name <glob>] becomes appduct events ls [selector] [--name <glob>].
• Criterion 3 becomes: "appduct events ls prints one signature line per declared event, --name <glob> narrows it, and an exact name prints the full schema; --json carries the same data."
• The CLI reference in the shipped skill should name appduct events ls.

---

Generated by Claude Code

[V3RON]

Approved by @V3RON on 2026-09-25.

Design

Premise, checked against main (4e64b33). It holds; #93, #94 and #96 have landed. The issue missed one thing: a daemon closes the session on any frame type it doesn't know (1008 unknown_message_type, terminal). A new SDK sending event registry frames to an older CLI would lose its session, so the ack now says whether the daemon accepts them.

Goal. An agent lists the events an app declared, with descriptions and payload shapes, before it waits on one.

Shape

// @appduct/shared
type EventDescriptor = { name: string; description: string; payload_schema?: Record<string, unknown> };
isEventDescriptor(v): v is EventDescriptor   // name: `event.name`'s rule; description: a tool's
type EventRegistrySnapshotMessage = { type: "event_registry_snapshot"; session_id; events: EventDescriptor[] };
type EventRegistryDeltaMessage = { type: "event_registry_delta"; session_id } &
  ({ operation: "upsert"; event: EventDescriptor } | { operation: "remove"; name: string });
SessionAckMessage.event_registry?: true
renderEventSignature(e): string              // "checkout_completed { orderId: string }"
"events.list": SessionSelectorParams & { name?: string; limit?: number; offset?: number }
            -> { events: EventDescriptor[]; total: number }   // sorted by name, glob before total
EVENT_KINDS += "events_changed"

• daemon. registry.ts becomes createRegistry<T extends { name: string }> for tools and events. Each session gets an event registry. The ack sets event_registry: true, and a bad frame closes with invalid_registry. events.list is a call. events_changed is a bus event like tools_changed, so it goes to the log only.
• CLI. appduct events ls [selector] [--name <glob>]. MCP. appduct_list_events goes in mcp/events-tool.ts.
• Swift, Kotlin. registerEvent(EventDescriptor) throws -> EventRegistration, shaped like registerTool. It sends frames only after an ack that carries event_registry.
• React Native. registerEvent({ name, description, payloadSchema? }) returns what registerTool returns and goes through the TurboModule's registerEvent(json) and unregisterEvent(name). The JS layer holds the Standard Schemas and gives the dev warnings.

Not in scope. Dev warnings in Swift and Kotlin: neither core has a dev log, and a raw JSON Schema has nothing to validate it against. appduct/client and hooks: not asked for.

Slices

1. Wire, daemon and events ls. (a) After an ack with the flag, a snapshot makes events.list return the event, and a remove delta takes it out. (b) A malformed frame closes with 1008 invalid_registry. (c) A session that sends no event frames lists { events: [], total: 0 }. (d) A snapshot after resume replaces the registry. (e) events ls prints signature lines, --name narrows them, an exact name prints the schema, and --json carries the same data. (f) events_changed reaches events.log only. (g) The TS suite passes fixtures/event-descriptors.json. (h) PROTOCOL.md and cli.md are updated.
2. appduct_list_events. Returns signature lines with total. name: "cart.*" narrows them, and an exact name adds payload_schema. The shipped skill says to list events before waiting on one.
3. Swift registerEvent. Passes the fixture. Every ack carrying the flag, resume included, is followed by a snapshot. The disposer sends a remove. With no flag, nothing is sent. A frames fixture covers snapshot and delta.
4. Kotlin registerEvent. Same as 3; parallel with 3.
5. React Native registerEvent. Criterion 1 end to end. In dev, an undeclared name and a payload that fails its schema each warn, and production posts as-is. TOOLS.md and writing-tools.md cover declaring events. Needs 3 and 4.

Decisions

• Ack flag stays. An app's SDK can be newer than the user's CLI, as it already can be for tool groups. The SDKs send event frames only after an ack with event_registry: true. Against an older CLI, the app keeps its session and its tools, and has no event catalog.
• Declared names follow the posted-name rule: any string up to 4096 characters, not the tool-name pattern. Any name an app already posts, dotted ones like cart.item_added included, can be declared without renaming.
• Dev warnings are React Native only. Swift and Kotlin don't warn about undeclared names or failing payloads. Neither core has a dev log or a JSON Schema validator. Criterion 5's warning applies to React Native.

[V3RON]

All five slices are up as one GitHub stack (#148): #143 (#124) ← #144 (#125) ← #145 (#126) ← #146 (#127) ← #147 (#128). Each is reviewed and device-tested and marked ready. The branches were stacked with merge commits, so no force pushes. Merge with gh stack merge.