Feature: Event-Driven Workflow Triggers

[jrob5756]

Summary

Add a lightweight trigger system so workflows can be automatically invoked by file changes, cron schedules, or webhooks via a new conductor watch command.

Motivation

The industry is shifting from request-response to persistent, always-on agent systems — Claude Code Channels (event-driven async via Telegram, Discord, webhooks), AWS EventBridge as "system's nervous system," and GitAgent (version-controlled AI agents triggered by git events). Conductor is CLI-invoked and single-shot today, with no way to react to external events automatically.

Proposed Design

Workflow Configuration

workflow:
  triggers:
    - type: watch
      path: ./reports/*.md
      event: modified              # or "created", "deleted", "any"
      debounce_seconds: 5          # avoid rapid re-triggers
    - type: schedule
      cron: "0 9 * * MON"         # every Monday at 9am
    - type: webhook
      port: 8080
      path: /trigger

CLI Commands

conductor watch workflow.yaml              # long-running, trigger-based execution
conductor watch workflow.yaml --once       # exit after first trigger fires
conductor watch workflow.yaml --web        # with dashboard (reuse existing web infra)
conductor watch workflow.yaml --dry-run    # show what would trigger, don't execute

Behavior

• Each trigger invocation creates a new workflow run (standard execution)
• Trigger metadata injected as workflow input variables:
  • {{ trigger.type }} — "watch", "schedule", or "webhook"
  • {{ trigger.path }} — file path (for watch triggers)
  • {{ trigger.timestamp }} — ISO 8601 trigger time
  • {{ trigger.payload }} — webhook request body (for webhook triggers)
• Concurrent runs configurable: max_concurrent_runs: 1 (default — queues additional triggers)

Trigger Types

Type	Library	Description
watch	watchdog	File system monitoring with glob pattern support
schedule	APScheduler	Cron-syntax scheduling
webhook	FastAPI (existing)	HTTP endpoint that triggers workflow on POST

Example: Auto-Summarize New Reports

workflow:
  name: auto-summarize
  triggers:
    - type: watch
      path: ./reports/*.md
      event: created
  entry_point: summarizer

agents:
  - name: summarizer
    model: gpt-5.2
    prompt: |
      Summarize the report at: {{ trigger.path }}
    routes:
      - to: \$end

conductor watch auto-summarize.yaml
# Now drop a new .md file in ./reports/ → workflow runs automatically

Why It Fits Conductor

• --web-bg background mode already exists — conductor watch is a natural extension
• File watching is straightforward with watchdog (well-maintained, cross-platform)
• Webhook reuses existing FastAPI server infrastructure from the web dashboard
• Each trigger creates a standard workflow run — no new execution semantics
• YAML-declarative trigger config, version-controllable alongside the workflow

Effort Estimate

Medium — new CLI command, trigger event loop, integration with existing run infrastructure. Webhook reuses FastAPI; file watch and cron are well-solved problems with existing libraries.