Trigger

1. Purpose

A trigger is a Hyperapp facet: external events wake an agent. A human configures when (which events) and what to do; events arrive at the Hyperapp, which matches them against the configuration and wakes the agent to respond.

Where the app facet is the agent acting on its own initiative, a trigger is the agent acting in response to something that happened outside.

2. Configuration

A human configures a trigger through a when / do form, rendered from the declaration:

• when — the fields that scope the event (for GitHub, a repository and a set of events). A field with dynamic options names a source the platform fetches from the Hyperapp by name.
• do — what the agent should do when it fires (an instruction).

Saving records a subscription: the configured fields and where to deliver.

3. Surface

A Hyperapp's trigger facet exposes:

• a declaration — { title, description, icon, when, do };
• an options endpoint the platform fetches by field name (dynamic when-options);
• a subscription endpoint (read to prefill, write to save);
• an events endpoint the source delivers to — the Hyperapp verifies each delivery with the sending connection's per-agent secret (looked up by the event's provider-side keys), matches, and wakes the agent.

4. Waking the agent

When an event matches a subscription, the Hyperapp wakes the agent — delivering to a wake target the platform provides, which starts one agent turn carrying the event. The platform provides the wake mechanism; deciding an event matches is the Hyperapp's.

5. Storage

A subscription is provider-agnostic: a wake target, opaque config (which events, an instruction), and a match key the Hyperapp builds for lookup — an event arrives with source-side keys (an installation, a repository) and no agent, so the Hyperapp looks its subscriptions up by that key. Where subscriptions live is the Hyperapp's choice: the platform offers Hypersub, the subscription store, or the Hyperapp keeps its own.