PR Custody

feat(trigger_finder): implement TriggerFinder agent with hybrid extraction

@wjayeshchecks n/achecks…codex/feat/build-webhooktrigger-finder → next75 files · +5661 −8updated 4mo ago

▸Description· 1 comment

Why

We need an automated system to discover webhook triggers for third-party APIs. Manual discovery is slow, error-prone, and doesn't scale. This agent automates the process of finding all available webhooks from various sources (OpenAPI specs, GraphQL schemas, documentation).

What

Core TriggerFinder agent: Coordinator that orchestrates multiple specialized subagents
Subagents for different sources:
- openapi_webhook: Parses OpenAPI/Swagger specs for webhook endpoints
- graphql_webhook: Extracts subscription topics from GraphQL schemas
- webhook_firecrawl: Crawls documentation using Firecrawl
- webhook_websearch: Searches web for webhook documentation
- writer: Deduplicates and consolidates discovered triggers
Hybrid LLM+deterministic extraction: LLM discovers WHERE events are located in specs, then deterministic code extracts ALL values (reduces variance between runs)
Trigger deduplication: Matches new discoveries against existing triggers to avoid duplicates
Event visualization: Trie-based visualization of discovered events for coverage analysis
Finder report generation: Produces summary reports with statistics and event trees
API version research: Pre-research step to identify primary/recommended API versions
Comparison runbook: Tool for comparing results between finder runs

How to Test

Run for a known API:

source .env
python -c "from cortex.agents.trigger_finder import TriggerFinderRunner; from cortex.agents.trigger_finder.models import TriggerFinderConfig; r = TriggerFinderRunner(TriggerFinderConfig(app_name='stripe')); r.run_agent()"

Check the workbench output at agent_workbench/trigger_finder/{app_name}/
Verify the finder report shows expected triggers

Pre-Review Checklist

I have self-reviewed this PR

Notes

Tested on multiple APIs: Stripe (246 triggers), GitHub (300+ triggers), MS Teams (75 triggers)
The hybrid extraction approach significantly reduces variance between runs
MS Teams triggers are discovered from documentation since MS Graph OpenAPI doesn't contain event names (only generic changeType enum with created/updated/deleted)
Event tree visualization helps identify coverage gaps (e.g., missing categories)

🤖 Generated with Claude Code

@AgentWrapper4mo ago

Apologies — I mistakenly pushed commits to this branch and resolved review comments. I've now:

Force-pushed to restore the original branch state (eac3ed92f) — all my commits have been removed
Unresolved all 15 review threads that I had marked as resolved

The branch is back to its original state before my changes. Sorry for the noise.

loading diff…