Skip to content

README.md

Latest commit

 

History

History
135 lines (104 loc) · 5.64 KB

README.md

File metadata and controls

135 lines (104 loc) · 5.64 KB

← Back to AIPass

Trigger

Purpose: Event bus for AIPass. Branches fire events, registered handlers react. Decouples producers from consumers — the module that detects a condition doesn't need to know what should happen next. Module: aipass.trigger Last Updated: 2026-04-22

Commands / Usage

drone @trigger fire <event> [data]              # Fire an event
drone @trigger list                             # List registered events
drone @trigger status                           # Event bus status
drone @trigger --help                           # Full help

Usage

CLI (via drone)

drone @trigger --help                    # Show available commands
drone @trigger medic on                  # Enable error auto-dispatch
drone @trigger medic off                 # Disable error auto-dispatch
drone @trigger medic status              # Show medic state
drone @trigger medic mute @branch        # Suppress errors from a branch
drone @trigger medic unmute @branch      # Resume errors from a branch
drone @trigger errors list               # List tracked errors
drone @trigger errors stats              # Error registry statistics
drone @trigger errors circuit-breaker    # Circuit breaker state
drone @trigger --version                 # Show version

Python API

from aipass.trigger.apps.modules.core import Trigger

# Fire an event — all registered handlers run
Trigger.fire("plan_file_created", path="/path/to/FPLAN-0042.md")

# Register a handler
def on_plan_file_created(**data):
    print(f"Plan created at {data['path']}")

Trigger.on("plan_file_created", on_plan_file_created)

# Remove a handler
Trigger.off("plan_file_created", on_plan_file_created)

Cross-branch error reporting

from aipass.trigger.apps.modules.errors import report_error

result = report_error(
    branch="api",
    error_type="ConnectionError",
    message="Timeout reaching upstream",
    source_file="client.py",
)
# Returns: {"is_new": True, "fingerprint": "abc123", "count": 1, ...}

Events

14 events registered via handlers/events/registry.py. All fire through Trigger.fire().

Event Handler Fired when Action
startup startup.py Branch session starts Error catch-up scan, memory rollover check
error_detected error_detected.py Error registered in log watcher (Medic v2) 8-gate dispatch pipeline, sends fix-it email to affected branch
error_logged error_logged.py Error detected in system logs (legacy) Rate-limited notification with medic gating
warning_logged warning_logged.py Warning detected in system logs Logged for monitoring, no dispatch
plan_file_created plan_file.py New PLAN file detected in filesystem Updates Flow's PLAN_REGISTRY.json
plan_file_deleted plan_file.py PLAN file removed from filesystem Marks plan as deleted in registry
plan_file_moved plan_file.py PLAN file moved or renamed Updates registry location
bulletin_created bulletin_created.py New system bulletin posted Propagates to all branch dashboards
memory_threshold_exceeded memory_threshold_exceeded.py Memory file approaches line limit (600 lines) Sends compression notification to branch
memory_template_updated memory_template_updated.py Memory template modified Pushes template updates to branches
memory_saved memory.py Memory file saved Placeholder for future rollover trigger
cli_header_displayed cli.py CLI displays headers Registration hook
pr_created pr_status_sync.py PR opened on GitHub Runs drone @prax status sync (fire-and-forget)
pr_merged pr_status_sync.py PR merged on GitHub Runs drone @prax status sync (fire-and-forget)

Medic

Built-in error monitoring subsystem. Watches logs for errors, fingerprints them via SHA1, deduplicates, and dispatches fix-it notifications to the responsible branch. Includes circuit breaker, per-branch rate limiting, and mute controls.

Architecture

trigger/
├── apps/
│   ├── trigger.py             # Entry point (auto-discovers modules)
│   ├── log_watcher_service.py # Persistent watcher process (systemd)
│   ├── modules/
│   │   ├── core.py            # Event bus (Trigger.fire/on/off)
│   │   ├── errors.py          # Error registry + cross-branch API
│   │   ├── medic.py           # Error monitoring commands
│   │   ├── branch_log_events.py  # Branch-level log event handling
│   │   └── log_events.py     # System-wide log event processing
│   └── handlers/
│       ├── events/            # One handler per event type
│       ├── log_watcher.py     # Branch log watcher (watchdog)
│       ├── error_registry.py  # SHA1 fingerprinting + circuit breaker
│       ├── error_reporter.py  # Cross-branch error API
│       └── medic_state.py     # Medic persistence (trigger_config.json)
└── tests/

Note: branch_log_events and log_events are auto-discovered modules that handle log-based event detection at branch and system levels respectively.

Integration Points

Depends On

  • aipass.prax — Logging via system_logger
  • aipass.cli — Console output and header formatting
  • Python stdlib (sys, pathlib, importlib)

Provides To

  • All modules — event bus (Trigger.fire, Trigger.on, Trigger.off)
  • All modules — cross-branch error reporting (report_error)
  • All modules — medic error monitoring and dispatch

Last Updated: 2026-04-22

← Back to AIPass