Adding a trigger

Some work starts outside: a push lands, an issue opens, a message arrives. A trigger lets those events wake an agent. A human configures when and what to do, events arrive at your Hyperapp, and your Hyperapp matches them and wakes the agent. This page describes the pieces and the shapes hosts understand. How you implement them is up to you.

What a trigger is

Where your pages are the agent acting on its own initiative, a trigger is the agent acting because something happened outside. The event's source is the service your connection reaches, and the trigger closes the loop: work flows in both directions.

The when / do form

A human scopes a trigger through a when / do form the host renders from your declaration:

• when: the fields that scope the event. For a code host, a repository and a set of events. A field with dynamic options names a source the host fetches from your 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.

What you expose

• a declaration: { title, description, icon, when, do }.
• an options endpoint the host fetches by field name, for dynamic when-options.
• a subscription endpoint: read to prefill, write to save.
• an events endpoint the service delivers to. Verify each delivery with the sending connection's per-agent secret, match it, and wake the agent.

Waking the agent

When an event matches a subscription, deliver it to the wake target the host provides. That starts one agent turn carrying the event. The host owns the wake mechanism. Deciding that an event matches is yours.

Example: repository events

The GitHub Hyperapp's trigger declaration:

{
  "title": "GitHub",
  "description": "Wake the agent when a repository moves",
  "when": {
    "repo": {
      "type": "select",
      "label": "Repository",
      "optionsFrom": "repos",
      "required": true
    },
    "events": {
      "type": "multiselect",
      "label": "Events",
      "options": ["issues", "issue_comment", "pull_request", "push", "release"],
      "required": true
    }
  },
  "do": {
    "instruction": { "type": "textarea", "label": "Instruction" }
  }
}

The repo field's options are dynamic: the host fetches options/repos, and the Hyperapp answers with the repositories the agent's connection can reach. Saving writes a subscription whose match key is {installation}/{repository}.

When GitHub delivers an event:

1. The events endpoint reads the raw body and the event name, and ignores kinds nobody can subscribe to.
2. It looks the grant up by the delivery's installation id, and verifies the signature with that grant's per-agent webhook secret.
3. It matches subscriptions by {installation}/{repository}, keeps the ones subscribed to this event kind, and delivers to each wake target.

The payload the agent wakes with is not the raw webhook. The Hyperapp trims the event to what it means and renders it as Markdown, with the configured instruction alongside.

Where subscriptions live

Your choice. Hypersub is the shared store, or keep your own. A subscription is provider-agnostic: a wake target, opaque config (which events, an instruction), and a match key you build for lookup. Events arrive with provider-side keys (an installation, a repository) and no agent, so you look subscriptions up by that key.