Waypoint

A production-grade, autonomous AI GitHub Issue Solver and software engineering platform designed for software teams and open-source maintainers. Features intelligent end-to-end issue resolution via Google Gemini, multi-language AST codebase indexing (Python, TypeScript/JavaScript, Go), cross-file call-graph dependency slicing with context window token packing, multi-model routing across Gemini, GPT-4o, Claude 3.5 Sonnet, and local Ollama with real-time USD cost observability, an interactive visual state-graph inspector and time-travel debugger with step-by-step playback, a multi-agent parallel solution tournament arena running isolated copy-on-write sandboxes with composite scoring, automated test runners with self-healing revision loops, AST secret scanners and banned API diff guards, HMAC-SHA256 GitHub Webhook bot automation, human-in-the-loop plan review checkpoints, and branch safety protection locks.

Features

Core Functionality

• Issue Ingestion & Context Parsing: Automatically ingests GitHub issues, pull request threads, discussion comments, author metadata, and repository file trees to formulate a comprehensive problem context.
• Structured Plan Generation: Employs Google Gemini with strict JSON schema enforcement (response_schema=ImplementationPlan) to produce root-cause analyses, exact file-level action items (modify, create, delete), step-by-step implementation instructions, and targeted verification strategies.
• Human-In-The-Loop (HITL) Checkpoints: Deterministic pause checkpoint powered by LangGraph state interrupts before any workspace modification. Human reviewers can approve, refine with natural-language feedback, or reject the proposed plan.
• Sandboxed Code Execution Engine: Clones repositories into ephemeral workspaces (.sandboxes/{run_id}) and performs isolated Git branch checkouts (ai-issue-solver/issue-{id}) with strict filesystem boundaries preventing project root contamination.
• Automated Test Runner & Validation Loop: Detects project test frameworks (pytest, npm test, cargo, go test) or executes AST syntax validation fallbacks. Upon test failure, the agent re-enters an automated code-revision loop with retry caps.
• Safe Draft Pull Request Creation: Automatically commits verified changes with clean Git attribution, pushes the namespaced feature branch, and opens a Draft Pull Request linked to the original issue with [ai-generated] labels.

Advanced Features

• Multi-Language AST Codebase Indexer: High-performance AST parser supporting Python (via Python ast), TypeScript/JavaScript (via AST regex tokenizers), and Go. Extracts function definitions, async functions, classes, methods, interfaces, type aliases, and module imports into unified symbol tables.
• Call-Graph Dependency Tracer & Impact Radius: Recursively analyzes function invocations and module imports across all indexed codebase files. Computes the blast radius of proposed symbol modifications up to $N$ hops to ensure all callers and dependent modules are gathered into context.
• Intelligent Context Slicer & Token Packer: Automatically collapses un-targeted method bodies in large source files (# ... [120 lines collapsed]) while preserving import headers, class definitions, and exact interface signatures, maximizing LLM context efficiency within character budgets.
• Interactive Force-Directed Dependency Graph UI: Real-time canvas visualization (/graph) featuring physics-based force-directed simulation (repulsion, edge attraction, velocity dampening), interactive pan and zoom controls, symbol kind color-coding, and symbol detail inspection panels.
• Multi-Model Registry & Pricing Catalog: Built-in capability registry mapping models (Gemini 2.0 Flash, Gemini 1.5 Pro, GPT-4o, GPT-4o-mini, Claude 3.5 Sonnet, Ollama CodeLlama) to token context windows, latency tiers, and exact per-1M input/output token pricing.
• Capability-Based Dynamic Model Router: Automatically inspects available environment API keys and routes tasks to the optimal model based on capability requirements (structured planning, rapid code synthesis, deep reasoning) and cost/speed preferences.
• Real-Time LLM Cost Observatory: Time-series metrics accumulator tracking token consumption, latency (ms), and USD expenditure per graph node and run. Features a live telemetry dashboard (/metrics) with global KPI counters, active routing matrices, and per-run drill-down logs.
• Time-Travel Debugger & State Snapshot Engine: Captures deep copies of IssueSolverState after every graph node execution. Features an interactive scrubber timeline (/debug/[id]), step-by-step state playback, and side-by-side delta diff viewers highlighting field mutations.
• Multi-Agent Parallel Solution Tournament Arena: Spawns $N$ concurrent agent workers exploring distinct solution hypotheses in parallel. Evaluates candidates using a composite scoring matrix (test pass rate 50%, diff conciseness 25%, plan specificity 25%) and crowns the optimal patch on the arena leaderboard (/arena/[id]).
• Isolated Copy-on-Write Sandboxes: Dedicated sandbox manager creating isolated ephemeral directories per tournament worker to prevent concurrent filesystem collisions.
• AST Secret & Credential Leakage Guard: Static analysis engine that scans code additions in git diffs for hardcoded secrets, including OpenAI keys (sk-*), GitHub tokens (ghp_*), AWS access keys (AKIA*), and private RSA keys.
• Banned Unsafe API Detector: Blocks dangerous code generation including eval(), exec(), subprocess.Popen(shell=True), os.system(), and destructive system commands (rm -rf /, DROP DATABASE).
• HMAC-SHA256 Webhook Receiver: Production webhook listener (/api/v1/webhooks/github) verifying GitHub's X-Hub-Signature-256 header to prevent spoofing and automatically spawning solver runs when issues are opened or labeled with ai-solve or bug.
• PR Review Self-Healing Revision Node: Ingests human reviewer comments on opened pull requests, extracts revision instructions, and triggers an automated patch cycle to address review feedback.
• Live Security & Webhook Compliance Panel: Interactive dashboard (/security) displaying active policy enforcement status, real-time webhook event feeds, and a built-in webhook payload simulator.

Safety & Governance

• Branch Protection Lock: Hardened assertion engine (_assert_branch_is_safe) preventing pushes to protected branches (main, master, develop, release/*, production).
• No Auto-Merge Policy: Absolute architectural invariant ensuring all pull requests are opened exclusively as drafts for human review.
• Mandatory Human-in-the-Loop Checkpoint: Execution halts after planning; sandbox code generation cannot proceed without explicit human authorization.
• Resource Sandboxing: Ephemeral workspace directories are cleaned up upon run completion, preventing disk bloat and cross-run leakage.

Tech Stack

Backend

• Python 3.11+ with FastAPI
• LangGraph & LangChain for cyclic state-machine orchestration
• Google GenAI SDK (gemini-2.0-flash, gemini-1.5-pro) for planning and code synthesis
• SQLAlchemy 2.0 (Async) with SQLite / PostgreSQL via aiosqlite
• PyGithub for GitHub REST API integrations
• GitPython for repository cloning, branch management, and git diff generation
• Pydantic v2 for strict schema validation and structured LLM outputs
• Pytest & Pytest-Asyncio for comprehensive test coverage

Frontend

• Next.js 15 (App Router) with TypeScript
• React 19 with Server & Client Components
• Tailwind CSS for custom design systems and glassmorphic UI
• Lucide React for consistent iconography
• HTML5 Canvas for force-directed dependency graph simulation
• Server-Sent Events (SSE) for real-time progress streaming and console telemetry

System Architecture

The system utilizes an asynchronous event-driven architecture combining LangGraph cyclic state machines, FastAPI background workers, and real-time SSE telemetry.

graph TD
    subgraph Client ["Frontend (Next.js 15 / React 19)"]
        UI["Dashboard & Runs Monitor"]
        GraphUI["Force-Directed Dep Graph (/graph)"]
        CostUI["Cost Observatory (/metrics)"]
        DebugUI["Time-Travel Debugger (/debug)"]
        ArenaUI["Tournament Arena (/arena)"]
        SecUI["Security & Webhooks (/security)"]
    end

    subgraph Server ["Backend (FastAPI / Python)"]
        API["FastAPI REST & SSE Router"]
        RunMgr["RunManager (Async Worker)"]
        Router["Model Router (Multi-LLM)"]
        SnapStore["Snapshot Store (Time-Travel)"]
        ArenaMgr["Arena Tournament Engine"]
        SecScanner["AST Security & Diff Guard"]
        WebhookServ["HMAC Webhook Receiver"]
    end

    subgraph Agent ["LangGraph State Machine"]
        ReadNode["read_issue"]
        ContextNode["gather_context (AST + Slicer)"]
        PlanNode["plan (Gemini / Multi-Model)"]
        HITL["HITL Checkpoint (interrupt_before)"]
        WorkNode["setup_workspace"]
        WriteNode["write_code"]
        ValNode["validate (Tests + Security)"]
        PRNode["create_pr (Draft + Safety)"]
    end

    subgraph Storage ["Storage & Sandboxes"]
        DB[(SQLite / PostgreSQL)]
        Sandboxes[".sandboxes/ (Ephemeral Git)"]
        GitHubAPI["GitHub REST API"]
        GeminiAPI["Google Gemini API"]
    end

    UI <--> API
    GraphUI <--> API
    CostUI <--> API
    DebugUI <--> API
    ArenaUI <--> API
    SecUI <--> API

    API --> RunMgr
    RunMgr --> Agent
    Agent --> Router
    Agent --> SnapStore
    Agent --> SecScanner
    RunMgr --> DB
    WriteNode --> Sandboxes
    ValNode --> Sandboxes
    PRNode --> GitHubAPI
    PlanNode --> GeminiAPI

Loading

Module Dependency Flow

graph LR
    subgraph Core_Engine ["Core Processing Flow"]
        Issue[GitHub Issue / Webhook] --> AST[AST Parser & Symbol Table]
        AST --> Slicer[Code Slicer & Call Graph]
        Slicer --> Router[Model Router]
        Router --> Planner[Gemini Structured Planner]
        Planner --> Checkpoint{HITL Approval?}
        Checkpoint -->|Approved| Sandbox[Ephemeral Sandbox]
        Checkpoint -->|Refine| Planner
        Sandbox --> Coder[Code Synthesis Engine]
        Coder --> SecGuard[Security Scanner]
        SecGuard -->|Clean| Tester[Automated Test Runner]
        SecGuard -->|Violation| Coder
        Tester -->|Passed| PR[Draft Pull Request]
        Tester -->|Failed| Coder
    end

    subgraph Telemetry_Flow ["Observability Flow"]
        Planner -.-> Snapshots[Snapshot Store]
        Coder -.-> Snapshots
        Tester -.-> Snapshots
        Router -.-> CostStore[Metrics Store]
        Sandbox -.-> Arena[Arena Tournament]
    end

Loading

Project Structure

Waypoint/
├── backend/
│   ├── app/
│   │   ├── agent/
│   │   │   ├── nodes/
│   │   │   │   ├── read_issue.py         # Issue ingestion & mock fallback node
│   │   │   │   ├── gather_context.py      # AST-aware context gathering node
│   │   │   │   ├── plan.py               # Structured plan generation node
│   │   │   │   ├── setup_workspace.py    # Sandbox git checkout node
│   │   │   │   ├── write_code.py         # Code modification & diff node
│   │   │   │   ├── validate.py           # Test runner & security guard node
│   │   │   │   ├── create_pr.py          # Draft PR creation & safety node
│   │   │   │   └── pr_healing.py         # Review comment self-healing node
│   │   │   ├── graph.py                  # LangGraph StateGraph assembly
│   │   │   └── state.py                  # IssueSolverState & Pydantic models
│   │   ├── api/
│   │   │   ├── runs.py                   # Run lifecycle & HITL action endpoints
│   │   │   ├── codebase.py               # Dependency graph & symbol endpoints
│   │   │   ├── metrics.py                # LLM cost & routing endpoints
│   │   │   ├── snapshots.py              # Time-travel state snapshot endpoints
│   │   │   ├── arena.py                  # Multi-agent tournament endpoints
│   │   │   └── webhooks.py               # HMAC GitHub webhook receiver
│   │   ├── db/
│   │   │   ├── models.py                 # SQLAlchemy Run & StepLog models
│   │   │   └── session.py                # Async session maker
│   │   ├── services/
│   │   │   ├── ast_parser.py             # Multi-language AST symbol parser
│   │   │   ├── symbol_table.py           # Repository-wide symbol indexer
│   │   │   ├── dependency_graph.py       # Call graph & blast radius tracer
│   │   │   ├── code_slicer.py            # Token budget context packer
│   │   │   ├── llm_registry.py           # Model pricing catalog & token estimator
│   │   │   ├── model_router.py           # Dynamic capability-based LLM router
│   │   │   ├── metrics_store.py          # In-memory time-series cost store
│   │   │   ├── snapshot_store.py         # Immutable state snapshot recorder
│   │   │   ├── arena_manager.py          # Tournament engine & composite scoring
│   │   │   ├── arena_sandbox.py          # Per-worker isolated sandboxes
│   │   │   ├── security_scanner.py       # Secret detection & banned API guard
│   │   │   ├── webhook_verifier.py       # HMAC-SHA256 signature verifier
│   │   │   ├── run_manager.py            # Async background task worker
│   │   │   ├── sandbox_service.py        # Ephemeral git workspace manager
│   │   │   ├── gemini_service.py         # Google Gemini integration
│   │   │   └── github_service.py         # PyGithub REST client
│   │   ├── config.py                     # App settings & environment loader
│   │   └── main.py                       # FastAPI initialization & diagnostics
│   ├── tests/                            # 148 automated unit & integration tests
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx                  # Dashboard with runs & feature cards
│   │   │   ├── issues/page.tsx           # Repository issues backlog
│   │   │   ├── runs/[id]/page.tsx        # Live run telemetry & HITL approval
│   │   │   ├── graph/page.tsx            # Force-directed dependency graph
│   │   │   ├── metrics/page.tsx          # Real-time LLM cost observatory
│   │   │   ├── debug/[id]/page.tsx       # Time-travel debugger & state replay
│   │   │   ├── arena/[id]/page.tsx       # Multi-agent tournament leaderboard
│   │   │   └── security/page.tsx         # Security policies & webhook activity
│   │   ├── components/                   # Reusable UI components
│   │   └── lib/                          # API clients & types
│   └── package.json
├── docs/
│   └── ARCHITECTURE_V2.md                # In-depth architectural documentation
└── README.md

API Documentation Overview

Waypoint exposes RESTful and SSE endpoints across all core capabilities:

• System Diagnostics: GET /health — Health check, feature flag status, and subsystem counts.
• Run Orchestration: POST /api/v1/runs/trigger — Trigger a new autonomous issue solver run.
• Run State: GET /api/v1/runs/{id} — Fetch run state, plan JSON, diffs, and PR URL.
• Live Telemetry: GET /api/v1/runs/{id}/events — Server-Sent Events (SSE) stream for real-time progress.
• HITL Approval: POST /api/v1/runs/{id}/approve — Approve plan and proceed to sandboxed coding.
• HITL Refinement: POST /api/v1/runs/{id}/refine — Submit feedback and trigger plan revision.
• HITL Rejection: POST /api/v1/runs/{id}/reject — Reject plan and cancel run execution.
• Codebase Graph: GET /api/v1/codebase/graph — Retrieve nodes and edges for dependency visualization.
• Impact Radius: POST /api/v1/codebase/impact — Compute blast radius for modified symbols.
• Symbol Lookup: GET /api/v1/codebase/symbols — Search symbol definitions by name.
• Cost Observability: GET /api/v1/metrics/global — Aggregate session tokens, USD cost, and call counts.
• Run Metrics: GET /api/v1/metrics/runs/{id} — Detailed per-node cost and token breakdown.
• Model Routing: GET /api/v1/metrics/routing — View active capability routing decisions.
• Time-Travel Timeline: GET /api/v1/snapshots/runs/{id}/timeline — Retrieve ordered state snapshots.
• State Diff: GET /api/v1/snapshots/runs/{id}/diff/{step_index} — Inspect field-level delta diffs.
• Tournament Creation: POST /api/v1/arena/create — Initialize a multi-agent solution arena.
• Tournament Execution: POST /api/v1/arena/{id}/start — Run parallel candidate synthesis.
• GitHub Webhooks: POST /api/v1/webhooks/github — Ingest HMAC-verified events and auto-solve issues.
• Webhook Activity: GET /api/v1/webhooks/activity — View recent webhook dispatch logs.

Performance Benchmarks & Safety Invariants

Performance Metrics

• AST Parsing Speed: < 10ms per 1,000-line Python/TypeScript source file.
• Context Slicing: Compresses 50KB+ files down to < 5KB interface outlines (10x token reduction).
• Time-Travel Snapshots: < 2ms snapshot capture latency with deep-copy delta diffing.
• Local Cache & In-Memory Lookups: < 1ms response time for metrics and symbol indexes.

Safety Invariants Verified by Tests (148/148 Passing)

Safety Invariant	Enforced By	Test Suite	Result
Branch Protection	SandboxService._assert_branch_is_safe()	test_safety_invariants.py	Verified
No Auto-Merge	github_service.py (No merge methods)	test_safety_invariants.py	Verified
Always Draft PRs	github_service.create_draft_pr()	test_safety_invariants.py	Verified
Secret Leakage Guard	security_scanner.scan_diff()	test_security_scanner.py	Verified
Banned API Blocker	security_scanner.scan_diff()	test_security_scanner.py	Verified
HMAC Verification	webhook_verifier.verify_signature()	test_webhooks.py	Verified
Sandbox Isolation	SandboxService & ArenaSandbox	test_stage5_sandbox.py	Verified

Getting Started

1. Launch Backend

cd backend
python -m venv .venv
# Windows:
.\.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

2. Launch Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000 to access the Waypoint dashboard.

4. Run Test Suite

cd backend
.\.venv\Scripts\python.exe -m pytest -v

---

Development Roadmap

Phase 1: Core Foundation & Agent State Machine (Completed)

• LangGraph cyclic state machine with read_issue, gather_context, plan, setup_workspace, write_code, validate, and create_pr nodes.
• PyGithub REST client with fallback mocks for unauthenticated local development.
• Ephemeral workspace manager with branch safety assertions (ai-issue-solver/*).

Phase 2: Human-in-the-Loop & Interactive Dashboard (Completed)

• Deterministic LangGraph interrupt checkpoint before workspace initialization.
• Next.js 15 dashboard with live Server-Sent Events progress streaming, unified git diff viewer, and plan review controls (Approve / Refine / Reject).
• Automated test runner detecting pytest, npm test, cargo, or fallback syntax checks.

Phase 3: AST Indexing & Codebase Dependency Slicer (Completed)

• Multi-language AST parser for Python, TypeScript/JavaScript, and Go.
• Repository-wide symbol table and cross-file call graph tracer.
• Token-budget code slicer collapsing untouched methods in large source files.
• Interactive force-directed dependency graph UI on HTML5 Canvas (/graph).

Phase 4: Multi-Model Routing & Cost Observability (Completed)

• Model registry and pricing catalog for Gemini, GPT-4o, Claude 3.5 Sonnet, and Ollama.
• Dynamic capability-based router matching task requirements against available API keys.
• Real-time USD and token usage metrics store with live telemetry dashboard (/metrics).

Phase 5: Time-Travel Debugger & Visual Inspector (Completed)

• Immutable state snapshot recorder capturing state copies after every node transition.
• Delta diff engine computing field mutations between adjacent steps.
• Time-travel debugger UI with scrubber slider, step playback, and before/after diff panels (/debug/[id]).

Phase 6: Multi-Agent Solution Tournament Arena (Completed)

• Parallel worker execution spawning $N$ concurrent agent hypotheses for difficult issues.
• Isolated copy-on-write sandboxes per worker to avoid filesystem collisions.
• Composite scoring matrix evaluating test pass rates, diff conciseness, and plan quality (/arena/[id]).

Phase 7: GitHub Webhook Bot, PR Self-Healing & Security Scan (Completed)

• HMAC-SHA256 signature verifier for secure GitHub webhook ingestion.
• AST secret scanner blocking OpenAI, GitHub, and AWS credentials in diffs.
• Banned API guard blocking eval, exec, shell=True, and destructive commands.
• PR review comment self-healing revision node pulling feedback from opened PRs.
• Live security compliance and webhook activity monitoring panel (/security).