feat(agents): supervisor + GitHub repo researcher + tracing

.env.example

@@ -27,3 +27,37 @@ GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
 GOOGLE_REDIRECT_URI=http://localhost:8000/api/v1/auth/oauth/google/callback
 FRONTEND_URL=http://localhost:5173
+
+# =============================================================================
+# REQUIRED: Agent platform encryption key
+# =============================================================================
+# Symmetric Fernet key used to encrypt every workspace's LLM provider API key
+# and GitHub PAT at rest. Without this:
+#   * Saving a workspace LLM key → 500 error → no agent can call an LLM.
+#   * Saving a GitHub PAT → 500 error → repo researcher can't read repos.
+#   * Any "agent settings" save returns "AGENTS_SECRET_KEY is not configured".
+#
+# Generate ONCE per deployment (32-byte url-safe base64, exactly 44 chars):
+#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#
+# DO NOT rotate after secrets are saved — there's no auto re-encryption.
+# Losing this key locks every workspace's LLM/GitHub credentials forever.
+# Treat it like JWT_SECRET: keep it in your secrets manager, back it up.
+AGENTS_SECRET_KEY=
+
+# Langfuse — optional admin-instance tracing for agent LLM calls.
+# When all three are set, app/agents/tracing.py registers LiteLLM callbacks
+# at startup and routes per-call telemetry. Per-call gating is governed by
+# the workspace's analytics_consent (off / errors_only / full). Leave blank
+# to disable tracing entirely.
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+LANGFUSE_HOST=
+
+# Agent invocation rate limits — operator-level (not per-workspace). Defaults
+# below are 10× the original spec. Override only if you need to throttle
+# harder or relax further.
+# AGENT_RATE_LIMIT_API_KEY_PER_HOUR=6000
+# AGENT_RATE_LIMIT_API_KEY_PER_DAY=60000
+# AGENT_RATE_LIMIT_USER_PER_DAY=10000
+# AGENT_RATE_LIMIT_WORKSPACE_PER_DAY=100000

.github/workflows/eval.yml

@@ -0,0 +1,75 @@
+name: Agent Evals (slow, costed)
+
+on:
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: 'Suite to run (fast/slow/all/single-test)'
+        required: true
+        default: 'slow'
+        type: choice
+        options:
+          - fast
+          - slow
+          - all
+          - single-test
+      test_path:
+        description: 'For single-test: relative path like evals/test_planner.py::TestX::test_y'
+        required: false
+        default: ''
+      profile:
+        description: 'Threshold profile (lenient/strict)'
+        required: false
+        default: 'lenient'
+        type: choice
+        options:
+          - lenient
+          - strict
+
+jobs:
+  eval:
+    runs-on: ubuntu-latest
+    environment: eval-llm-keys
+    timeout-minutes: 60
+    defaults:
+      run:
+        working-directory: backend
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: latest
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install deps
+        run: uv sync --frozen --extra agents --extra dev --extra evals
+
+      - name: Run eval suite
+        env:
+          EVAL_MODEL: ${{ secrets.EVAL_MODEL }}
+          EVAL_LLM_KEY: ${{ secrets.EVAL_LLM_KEY }}
+          EVAL_LLM_BASE_URL: ${{ secrets.EVAL_LLM_BASE_URL }}
+          EVAL_THRESHOLD_PROFILE: ${{ inputs.profile }}
+        run: |
+          case "${{ inputs.suite }}" in
+            fast)        make -C evals fast ;;
+            slow)        make -C evals slow ;;
+            all)         make -C evals fast slow ;;
+            single-test) uv run --extra agents --extra dev --extra evals pytest "${{ inputs.test_path }}" -v ;;
+          esac
+
+      - name: Upload reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: eval-reports-${{ github.run_id }}
+          path: backend/evals/reports/
+
+      - name: Comment on PR with results (if applicable)
+        if: always()
+        run: |
+          echo "TODO: gh pr comment with eval-summary diff"

.github/workflows/test.yml

@@ -0,0 +1,84 @@
+name: Tests & Fast Evals
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+
+    # Most service / scenario tests hit a real Postgres + Redis (the agent
+    # platform's encryption + per-user undo flows can't be faithfully
+    # exercised against fakes). Spin both up as job services and point the
+    # backend env at them; the `localhost` address resolves to the service
+    # via GitHub Actions' default networking.
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: archflow
+          POSTGRES_PASSWORD: archflow
+          POSTGRES_DB: archflow
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd "pg_isready -U archflow -d archflow"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+      redis:
+        image: redis:7-alpine
+        ports: ["6379:6379"]
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      DATABASE_URL: postgresql+asyncpg://archflow:archflow@localhost:5432/archflow
+      DATABASE_URL_SYNC: postgresql://archflow:archflow@localhost:5432/archflow
+      REDIS_URL: redis://localhost:6379/0
+      JWT_SECRET: test-secret-not-for-production
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          version: latest
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install deps
+        run: uv sync --frozen --extra agents --extra dev --extra evals
+
+      # Generate a throwaway Fernet key so agents code that wraps secrets
+      # at rest doesn't fail at import time. Real deployments set this in
+      # their environment; CI just needs *something* valid.
+      - name: Generate AGENTS_SECRET_KEY
+        run: |
+          KEY=$(uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
+          echo "AGENTS_SECRET_KEY=$KEY" >> "$GITHUB_ENV"
+
+      # No explicit `alembic upgrade` step: backend/conftest.py auto-derives
+      # an `archflow_test` sibling DB, creates it if missing, and migrates
+      # it on session start. This is the same code path that protects the
+      # local dev DB from being truncated by accident.
+      - name: Unit tests
+        run: uv run pytest tests/ -v
+
+      # uv treats this project as a virtual workspace ("source = virtual"),
+      # which means `evals` isn't materialised in site-packages even though
+      # setuptools packages.find lists it. Put backend/ on PYTHONPATH so
+      # the eval conftest's `from evals.lib.judge import ...` resolves.
+      - name: Fast eval suite (deterministic, no LLM cost)
+        env:
+          PYTHONPATH: ${{ github.workspace }}/backend
+        run: make -C evals fast

.gitignore

@@ -19,6 +19,14 @@ frontend/src/api/generated/
 # Keep our shared frontend lib/ despite a possible global "lib/" ignore rule
 !frontend/src/lib/
 !frontend/src/lib/**
+# Same exception for the backend eval helpers (judge, agent_helpers, etc.) —
+# the global `lib/` rule was hiding the entire `backend/evals/lib/` package
+# from git, which then broke CI's eval suite with ModuleNotFoundError.
+# The `__pycache__` re-ignore below stops the wildcard exception from
+# accidentally tracking compiled bytecode.
+!backend/evals/lib/
+!backend/evals/lib/**
+backend/evals/lib/**/__pycache__/
 
 # Environment
 .env
@@ -48,3 +56,7 @@ Thumbs.db
 
 # Taskmaster (local planning / session state)
 .taskmaster/
+
+# Temporary working files (specs, scratch) — never commit
+tmp/
+ArchFlow.iml

Makefile

@@ -1,10 +1,10 @@
-.PHONY: dev dev-deps dev-infra dev-backend dev-frontend setup test test-backend test-frontend build up down db-migrate db-upgrade db-downgrade db-sweep-undo api-codegen lint
+.PHONY: dev dev-deps dev-infra dev-backend dev-frontend kill-dev setup test test-backend test-frontend build up down db-migrate db-upgrade db-downgrade db-sweep-undo api-codegen lint
 
 # ─── Development ───────────────────────────────────────────────
 
 dev: dev-deps dev-infra db-upgrade
 	@echo "Starting backend and frontend..."
-	@trap 'kill 0' EXIT; \
+	@trap 'kill 0 2>/dev/null; pids=$$(lsof -ti tcp:8000,5173 2>/dev/null); [ -n "$$pids" ] && kill -9 $$pids 2>/dev/null; exit 0' INT TERM EXIT; \
 		$(MAKE) dev-backend & \
 		$(MAKE) dev-frontend & \
 		wait
@@ -17,12 +17,21 @@ dev-deps:
 dev-infra:
 	docker compose -f docker/docker-compose.dev.yml up -d
 
+# Pre-kill anything still bound to 8000 — uvicorn --reload sometimes orphans
+# its worker on Ctrl+C while serving an SSE stream, leaving the port held.
 dev-backend:
+	-@pids=$$(lsof -ti tcp:8000 2>/dev/null); [ -n "$$pids" ] && kill -9 $$pids 2>/dev/null; true
 	cd backend && uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 
 dev-frontend:
+	-@pids=$$(lsof -ti tcp:5173 2>/dev/null); [ -n "$$pids" ] && kill -9 $$pids 2>/dev/null; true
 	cd frontend && npm run dev
 
+# Manual nuke — frees both dev ports without restarting.
+kill-dev:
+	-@pids=$$(lsof -ti tcp:8000,5173 2>/dev/null); [ -n "$$pids" ] && kill -9 $$pids 2>/dev/null; true
+	@echo "Ports 8000 and 5173 freed."
+
 setup: dev-deps dev-infra
 	@echo "Running initial setup..."
 	cd backend && uv run alembic revision --autogenerate -m "initial schema"

README.md

@@ -72,11 +72,18 @@ L3                      Component
 - **Pinned / Recent** on the Overview dashboard.
 - Full-text search across all objects and diagrams (⌘K / Ctrl+K).
 
+### 🤖 AI agents
+- **Multi-agent supervisor** orchestrating specialized sub-agents (planner, researcher, diagram, critic) over a LangGraph state machine — handles "describe this", "build me X", "review this design" inside the chat panel.
+- **GitHub Repo Researcher** — link any Container/System to a GitHub URL and a read-only sub-agent fetches code, READMEs, issues, PRs, commits, and diffs to ground its answers in the actual implementation. Per-workspace GitHub PAT (encrypted at rest); 9 tools with per-turn LRU cache.
+- **Diagram Explainer** — one-click natural-language summary of any object or connection, with inline popovers.
+- **Provider-agnostic LLMs** via LiteLLM — pick OpenAI, Anthropic, OpenRouter, or any OpenAI-compatible endpoint per workspace; model + base URL stored encrypted.
+- **Tool-call streaming UI** — live tool icons, sub-agent transitions, applied-change pills, and full transcripts that survive page reloads.
+- **Optional Langfuse tracing** — per-workspace consent (`off` / `errors_only` / `full`).
+
 ### 🔌 Extensibility
 - **REST API** (OpenAPI / Swagger UI at `/docs`) + orval-generated TypeScript client.
 - **API keys** with prefix-based detection (`ak_…`), first-class citizens alongside JWT.
 - **Webhooks** for `object.*`, `connection.*`, `diagram.*`, and more.
-- Optional **AI insights** (Claude) — summarize an object's role, spot missing connections.
 - **JSON export / import** for migration or CI snapshotting.
 
 ### 🌐 Realtime collaboration
@@ -97,6 +104,7 @@ L3                      Component
 - Alembic migrations
 - PostgreSQL 16
 - Redis (realtime fanout)
+- LangGraph + LiteLLM (agents)
 - pytest + pytest-asyncio
 - uv package manager
 
@@ -247,10 +255,30 @@ DATABASE_URL=postgresql+asyncpg://archflow:archflow@localhost:5432/archflow
 JWT_SECRET=change-me-in-production
 BACKEND_CORS_ORIGINS=http://localhost:5173
 
-# Optional — enables AI insights on ModelObjects
-ANTHROPIC_API_KEY=sk-ant-...
+# Optional — Langfuse tracing for agent calls (per-workspace consent gates each call).
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+LANGFUSE_HOST=
+```
+
+### ⚠️ Required for AI agents: `AGENTS_SECRET_KEY`
+
+If you want the AI agent features (supervisor, repo researcher, diagram explainer) to work, you **must** set `AGENTS_SECRET_KEY` in `.env`. It's the symmetric Fernet key that encrypts every workspace's stored LLM provider API key and GitHub PAT at rest.
+
+**Without it:**
+- Saving a workspace LLM key → 500 error → no agent can reach an LLM
+- Saving a GitHub PAT → 500 error → repo researcher can't read repos
+
+Generate **once per deployment** and store like any other secret:
+
+```bash
+python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
 ```
 
+> 🛑 **Don't rotate it after secrets are saved.** There's no automatic re-encryption — losing this key locks every workspace's LLM and GitHub credentials forever. Back it up alongside `JWT_SECRET`.
+
+LLM provider keys (OpenAI / Anthropic / OpenRouter / …) and the GitHub PAT for the repo-researcher are stored **per-workspace** in the database (encrypted by `AGENTS_SECRET_KEY`) — not in `.env`. Configure them from the workspace Settings page.
+
 ---
 
 ## 🐛 Troubleshooting

backend/Dockerfile

@@ -2,11 +2,10 @@ FROM python:3.12-slim AS builder
 
 WORKDIR /app
 COPY pyproject.toml .
+COPY . .
 
 RUN pip install uv && \
-    uv pip install --system -r pyproject.toml
-
-COPY . .
+    uv pip install --system ".[agents]"
 
 FROM python:3.12-slim
 

backend/alembic/versions/91e6520f52f4_notifications.py

@@ -19,10 +19,47 @@
 
 
 def upgrade() -> None:
-    """Upgrade schema."""
-    pass
+    """Upgrade schema.
+
+    Mirrors ``app.models.notification.Notification`` (UUIDMixin + TimestampMixin
+    + per-user notification fields). The original revision shipped empty,
+    which only worked when the schema was bootstrapped via
+    ``Base.metadata.create_all`` outside Alembic. Restoring the real CREATE
+    so a clean ``alembic upgrade head`` builds a working schema.
+    """
+    op.create_table(
+        "notifications",
+        sa.Column("id", sa.dialects.postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.dialects.postgresql.UUID(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("kind", sa.String(64), nullable=False),
+        sa.Column("title", sa.String(255), nullable=False),
+        sa.Column("body", sa.Text(), nullable=True),
+        sa.Column("target_url", sa.String(512), nullable=True),
+        sa.Column("read_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index(
+        "ix_notifications_user_id", "notifications", ["user_id"]
+    )
 
 
 def downgrade() -> None:
     """Downgrade schema."""
-    pass
+    op.drop_index("ix_notifications_user_id", table_name="notifications")
+    op.drop_table("notifications")