Research and design event system for bot triggers #41

New issue

Open

opened 2026-03-25 13:53:35 +00:00 by timur · 1 comment

timur commented

2026-03-25 13:53:35 +00:00

Owner

Context

Per hero_archipelagos#40, bots need to listen to events and automatically trigger workflow execution. No event infrastructure currently exists.

Research Needed

What event sources should be supported? (Forgejo webhooks, internal hero service events, external APIs, cron/scheduled)
What pub/sub or event bus architecture fits the hero ecosystem?
How do events map to bot workflow triggers?
Should events be processed by hero_proc (as scheduled actions) or a dedicated event router?

Possible Event Sources

Forgejo webhooks (commits, PRs, issues, releases)
Hero service lifecycle events (via hero_proc)
HTTP webhook receiver (generic external events)
Scheduled/cron triggers
Manual triggers (UI button)

Deliverable

A design document proposing the event architecture, data model, and integration points.

References

Parent issue: #40

## Context Per hero_archipelagos#40, bots need to listen to events and automatically trigger workflow execution. No event infrastructure currently exists. ## Research Needed - What event sources should be supported? (Forgejo webhooks, internal hero service events, external APIs, cron/scheduled) - What pub/sub or event bus architecture fits the hero ecosystem? - How do events map to bot workflow triggers? - Should events be processed by hero_proc (as scheduled actions) or a dedicated event router? ## Possible Event Sources - Forgejo webhooks (commits, PRs, issues, releases) - Hero service lifecycle events (via hero_proc) - HTTP webhook receiver (generic external events) - Scheduled/cron triggers - Manual triggers (UI button) ## Deliverable A design document proposing the event architecture, data model, and integration points. ## References - Parent issue: #40

timur referenced this issue

2026-03-25 14:15:12 +00:00

Intelligent automation app #40

timur commented

2026-03-26 09:49:38 +00:00

Author

Owner

Event System Research Notes

Requirements

Bots need to listen to events from multiple sources and trigger workflow execution. The system must be:

Generic: any event source can be plugged in
Configurable: users define which events trigger which bot workflows
Reliable: events should not be lost (at-least-once delivery)

Existing Infrastructure Survey

Component	Event Capability	Notes
hero_proc	Scheduler (cron/interval)	Can trigger actions on schedule, but no external event intake
hero_proxy	Service discovery	Knows which services are running, could route webhooks
Forgejo	Webhooks	Sends HTTP POST to configured URLs on git events
hero_osis	OSIS change notifications	Could detect object changes if implemented

Proposed Architecture: Event Router Service

External Sources          Event Router              Consumers
─────────────────    ─────────────────────    ──────────────
Forgejo webhooks ──→ │                     │ ──→ Bot workflow trigger
HTTP webhooks    ──→ │  hero_event_router   │ ──→ hero_proc job creation  
Cron/schedule    ──→ │  (new service)       │ ──→ Activity log
OSIS changes     ──→ │                     │ ──→ Notifications
                     ─────────────────────

Option A: Standalone event router service

New hero_event_router service with OpenRPC API
Listens on Unix socket, receives events via JSON-RPC
Maintains event → trigger mappings in OSIS
Dispatches to hero_proc for workflow execution
Pro: clean separation, dedicated service
Con: new service to maintain

Option B: Extension of hero_proc

Add event intake endpoints to hero_proc's existing RPC
hero_proc already has scheduler, actions, jobs — natural fit
Webhook receiver as a built-in action type
Pro: leverages existing infrastructure
Con: expands hero_proc's scope

Option C: Event handling in hero_proxy

hero_proxy already handles HTTP routing
Add webhook endpoint that maps to service calls
Pro: already the HTTP entry point
Con: proxy should stay stateless

Recommendation

Option B (extend hero_proc) seems most pragmatic for MVP:

hero_proc already orchestrates execution
Adding an event.register / event.emit RPC method is straightforward
Webhook receiver can be an HTTP endpoint in hero_proc_ui
Cron triggers already exist via SchedulePolicy

Event Data Model (Draft)

EventSource:
  id: String
  source_type: enum (webhook, cron, osis_change, manual)
  config: EventSourceConfig  # URL path, cron expr, object type, etc.

EventTrigger:
  id: String
  event_source_id: String
  filter: EventFilter  # Match rules (branch, event type, etc.)
  action: TriggerAction  # workflow_id + bot_id + inputs mapping

EventLog:
  id: String
  source_id: String
  payload: String  # JSON
  matched_triggers: Vec<String>
  timestamp: u64

Next Steps

Decide between Option A/B/C
Define OSchema for event types
Implement webhook receiver endpoint
Create Forgejo webhook integration as first event source

## Event System Research Notes ### Requirements Bots need to listen to events from multiple sources and trigger workflow execution. The system must be: - **Generic**: any event source can be plugged in - **Configurable**: users define which events trigger which bot workflows - **Reliable**: events should not be lost (at-least-once delivery) ### Existing Infrastructure Survey | Component | Event Capability | Notes | |-----------|-----------------|-------| | hero_proc | Scheduler (cron/interval) | Can trigger actions on schedule, but no external event intake | | hero_proxy | Service discovery | Knows which services are running, could route webhooks | | Forgejo | Webhooks | Sends HTTP POST to configured URLs on git events | | hero_osis | OSIS change notifications | Could detect object changes if implemented | ### Proposed Architecture: Event Router Service ``` External Sources Event Router Consumers ───────────────── ───────────────────── ────────────── Forgejo webhooks ──→ │ │ ──→ Bot workflow trigger HTTP webhooks ──→ │ hero_event_router │ ──→ hero_proc job creation Cron/schedule ──→ │ (new service) │ ──→ Activity log OSIS changes ──→ │ │ ──→ Notifications ───────────────────── ``` **Option A: Standalone event router service** - New hero_event_router service with OpenRPC API - Listens on Unix socket, receives events via JSON-RPC - Maintains event → trigger mappings in OSIS - Dispatches to hero_proc for workflow execution - Pro: clean separation, dedicated service - Con: new service to maintain **Option B: Extension of hero_proc** - Add event intake endpoints to hero_proc's existing RPC - hero_proc already has scheduler, actions, jobs — natural fit - Webhook receiver as a built-in action type - Pro: leverages existing infrastructure - Con: expands hero_proc's scope **Option C: Event handling in hero_proxy** - hero_proxy already handles HTTP routing - Add webhook endpoint that maps to service calls - Pro: already the HTTP entry point - Con: proxy should stay stateless ### Recommendation **Option B** (extend hero_proc) seems most pragmatic for MVP: - hero_proc already orchestrates execution - Adding an `event.register` / `event.emit` RPC method is straightforward - Webhook receiver can be an HTTP endpoint in hero_proc_ui - Cron triggers already exist via SchedulePolicy ### Event Data Model (Draft) ``` EventSource: id: String source_type: enum (webhook, cron, osis_change, manual) config: EventSourceConfig # URL path, cron expr, object type, etc. EventTrigger: id: String event_source_id: String filter: EventFilter # Match rules (branch, event type, etc.) action: TriggerAction # workflow_id + bot_id + inputs mapping EventLog: id: String source_id: String payload: String # JSON matched_triggers: Vec<String> timestamp: u64 ``` ### Next Steps 1. Decide between Option A/B/C 2. Define OSchema for event types 3. Implement webhook receiver endpoint 4. Create Forgejo webhook integration as first event source

timur referenced this issue

2026-03-26 09:49:44 +00:00

Generic event configuration UI for bot workflow triggers #42