Interface ProtocolEvents<C>

Plugin asks host to negotiate protocol + API compatibility.

Host replies with accepted mode/result for protocol + API compatibility.

Server-side registry sync for known online modules. Sent to newly authenticated peers to bootstrap module discovery.

Broadcast when a module's heartbeat expires (unhealthy).

Broadcast when a previously unhealthy module resumes heartbeating (healthy again).

Broadcast to all peers when a module announces itself, with its identity, static metadata, and declared dependencies. Host can use this to decide when to prepare/configure modules based on their needs and capabilities. Module that registering self can use this to declare its presence and what it offers, and to trigger orchestration flows in the host or other modules.

NOTICE: Modules that would love to discover peers SHOULD NOT wait or listen to this event, instead module:announced or module:de-announced, or registry:modules:sync and registry:modules:health:* events for more reliable discovery and tracking.

Broadcast to all peers when a module successfully announces.

Broadcast to all peers when a module is unregistered (disconnect, heartbeat expiry, error, etc).

Prepare completed. Host can move into config apply/validate.

Example: module:prepared { missingDependencies: [] }

Module needs configuration to proceed to prepared/configured.

Lifecycle status updates for orchestration/UX.

Example: module:status { phase: "ready" }

Ask the module to validate current config (host → module).

Validation response (module → host), with optional plan suggestions.

Status updates for validation (module → host).

Configuration planning request (host → module).

Configuration planning response (module → host).

Status updates for planning (module → host).

Commit a config as "active" (host → module).

Status updates for commit (module → host).

Configuration fully applied and active (module → host).

Capability offer emitted after module configuration.

Capability needs configuration before activation.

Request a phase transition (module → host).

Push configuration down to module (host → module).

Register the current module instance as a consumer for an event or event group.

Unregister the current module instance from an event consumer registration.

Spark used for allowing agents in a network to raise an event toward the other destinations (e.g. character).

DO:

• Use notify for episodic events (alarms/pings/reminders) with minimal payload.
• Use command for high-level intent; let sub-agents translate into their own state machines.
• Use emit for ack/progress/completion; include ids for tracing/dedupe.
• Route via destinations; keep payloads small; use context:update for richer ideas.
• Dedupe/log via id/eventId for observability.

DOn't:

• Stream high-frequency telemetry here (keep a separate channel).
• Stuff large blobs into payload/contexts; prefer refs/summaries.
• Assume exactly-once; add retry/ack on critical paths. You may rely on id/eventId for dedupe.
• Allow untrusted agents to broadcast without auth/capability checks.

Examples:

• Minecraft attack/death: kind=alarm, urgency=immediate (fast bubble-up). e.g., fromAgent='minecraft', headline='Under attack by witch', payload includes hp/location/gear.
• Cat bowl empty from HomeAssistant: kind=alarm, urgency=soon.
• IM/email "read now": kind=ping, urgency=immediate.
• Action Required email: kind=reminder, urgency=later.

destinations controls routing (e.g. ['character'], ['character','minecraft-agent']).

Acknowledgement/progress/state for a spark or command (bidirectional). Examples:

• Character: state=working, note="Seen it, responding".
• Sub-agent: state=done, note="Healed and safe".
• Sub-agent: state=blocked/dropped with note when it cannot comply.
• Minecraft: state=working, note="Pillared up; healing" in reply to a command.

Character issues instructions or context to a sub-agent. interrupt: force = hard preempt; soft = merge/queue. Examples:

• Witch attack: interrupt=force, priority=critical, intent=action with options (aggressive/cautious). e.g., options to block/retreat vs push with shield/sword, with fallback steps.
• Prep plan: interrupt=soft, priority=high, intent=plan with steps/fallbacks.
• Contextual hints: intent=context with contextPatch ideas/hints.