bkinnightskytw
/
agent-orchestrator
mirror of https://github.com/ComposioHQ/agent-orchestrator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
agent-orchestrator/docs/design
History
Deepak Veluvolu 852f1f93c8
fix: added GraphQL batch PRfeat: add GraphQL batch PR enrichment for orchestrator polling enrichment for orchestrator polling (fixes #608) (#637) 
## Approach

  The orchestrator polling loop previously made individual API calls for each PR's
  state, CI status, and review decision - 3 separate calls per PR per poll.
  With multiple PRs being monitored, this quickly exhausted GitHub's 5,000-point
  hourly rate limit.

  This PR implements GraphQL batching using aliases, which allows fetching data
  for up to 25 PRs in a single GraphQL query. Additionally, a 2-Guard ETag
  strategy is used to skip queries entirely when nothing has changed.

  ## Implementation

  ### GraphQL Batching
  - `generateBatchQuery()` creates a single GraphQL query with unique aliases (pr0, pr1, pr2...)
  - Each PR gets the same set of fields: state, CI status, review decision, mergeability
  - Uses inline fragments for union types (CheckRun/StatusContext)
  - Variable types: String! for owner/repo, Int! for PR numbers

  ### 2-Guard ETag Strategy
  Before running expensive GraphQL queries, two lightweight REST ETag checks detect if
  anything changed:

  **Guard 1 (PR List ETag):**
  - Checks `/repos/{owner}/{repo}/pulls` with If-None-Match header
  - Returns 304 if no changes → skips GraphQL (0 points)
  - Detects: New commits, title/body edits, labels, reviews, state changes

  **Guard 2 (Commit Status ETag):**
  - Checks `/repos/{owner}/{repo}/commits/{sha}/status` per cached PR
  - Returns 304 if no changes → skips GraphQL (0 points)
  - Detects: CI status transitions (failing → passing, passing → failing, etc.)

  ### Caching
  - LRU caches for PR metadata (max 200 entries), ETags (100/500 entries)
  - Cache misses trigger individual API fallback via lifecycle-manager
  - No placeholder caching on errors - allows proper fallback behavior

  ## Impact

  - **API reduction:** ~88% fewer REST calls (216 vs 1,800 calls/hour for 5 PRs)
  - **GraphQL efficiency:** Batch query fetches 25 PRs for ~40 points vs ~400 for individual calls
  - **Polling interval:** Still 30s, but most polls return cached data (0 cost)
  - **Fallback:** Individual SCM calls still work for edge cases (permissions, cache misses)

  ## Testing

  - Unit tests for query generation and parsing helpers
  - Integration tests for real GraphQL API calls (skipped by default)
  - Covers batch failures, partial success, empty arrays, edge cases
 		2026-03-30 00:31:04 +05:30
..
screenshots feat(web): redesign dashboard, session detail, and orchestrator terminal (#125) 2026-02-20 18:43:57 +05:30
README.md feat: add PR claim flow for agent sessions (#326) 2026-03-07 03:54:19 +05:30
competitive-analysis-raw.md feat(web): redesign dashboard, session detail, and orchestrator terminal (#125) 2026-02-20 18:43:57 +05:30
design-brief-v1.md feat(web): redesign dashboard, session detail, and orchestrator terminal (#125) 2026-02-20 18:43:57 +05:30
design-brief.md feat(web): redesign dashboard, session detail, and orchestrator terminal (#125) 2026-02-20 18:43:57 +05:30
feedback-pipeline-explainer.html feat(core): add feedback tools contracts, validation, storage, and dedupe 2026-03-10 22:31:39 +05:30
feedback-routing-and-followup-design.md feat(core): add feedback tools contracts, validation, storage, and dedupe 2026-03-10 22:31:39 +05:30
graphql-batching-implementation.md fix: added GraphQL batch PRfeat: add GraphQL batch PR enrichment for orchestrator polling enrichment for orchestrator polling (fixes #608) (#637) 2026-03-30 00:31:04 +05:30
orchestrator-terminal-design-brief.md feat(web): redesign dashboard, session detail, and orchestrator terminal (#125) 2026-02-20 18:43:57 +05:30
session-detail-design-brief.md feat(web): redesign dashboard, session detail, and orchestrator terminal (#125) 2026-02-20 18:43:57 +05:30
session-replacement-handoff.md feat: add PR claim flow for agent sessions (#326) 2026-03-07 03:54:19 +05:30
token-reference.css feat(web): redesign dashboard, session detail, and orchestrator terminal (#125) 2026-02-20 18:43:57 +05:30

README.md

ao Dashboard — Design Research Artifacts

Compiled February 2026 via competitive analysis, Playwright CSS extraction, and codebase audit.

Documents

File Description
design-brief.md Main design brief — competitive analysis, full color palette, typography, all component specs, anti-patterns, implementation stack recommendation, and current codebase audit
session-detail-design-brief.md Design spec for /sessions/[id] — the single-agent investigation view
orchestrator-terminal-design-brief.md Design spec for the orchestrator terminal — full-viewport command center with status strip
session-replacement-handoff.md Design plan for successor sessions, PR takeover, and context handoff after replacing a worker
token-reference.css Ready-to-use CSS — drop-in replacement for globals.css @theme block
competitive-analysis-raw.md Raw research notes from all 14 competitor sites (Linear, Vercel, Railway, Fly.io, Inngest, Temporal, Grafana, WandB, LangSmith, Retool, Render, PlanetScale, Supabase, GitHub Copilot)
design-brief-v1.md Original v1 brief (text-only research, pre-Playwright CSS extraction) — kept for reference

Screenshots

File Description
screenshots/linear-homepage.png Linear.app captured via Playwright (311KB) — source for verified CSS token extraction
screenshots/railway-homepage.png Railway.app captured via Playwright (444KB) — visual palette reference

Research Methods

Phase 1 — Text analysis: Two parallel research agents analyzed 14 competitor product sites via WebFetch, extracting visual patterns, color systems, and design philosophy from HTML/CSS content.

Phase 2 — Playwright CSS extraction: Installed @playwright/mcp and extracted live CSS custom properties from linear.app using document.styleSheets enumeration. This yielded ground-truth values for Linear's token system — the most rigorous competitive design data available without access to their Figma files.

Phase 3 — Playwright screenshots: Captured screenshots of Linear and Railway via headless Chromium for visual reference.

Phase 4 — Codebase audit: Read the entire packages/web/ source (components, types, CSS tokens) to map research recommendations against the actual implementation. Produced implementation audit sections in each brief with prioritized delta tables.

Key Findings

  1. Linear's verified token system (via Playwright CSS extraction) is the closest design benchmark. See design-brief.md §1.
  2. Current dashboard uses GitHub-inspired colors (#0d1117 base). Recommended shift: blue-cast dark (#0C0C11). See design-brief.md §7.
  3. The 6-level attention zone system (merge → respond → review → pending → working → done) is architecturally correct and well-implemented. Visual polish is the primary gap.
  4. Highest-impact single change: load Inter Variable via next/font/google. Immediately elevates the typography to Linear/Supabase tier.
  5. Orchestrator terminal needs visual differentiation (violet accent, status strip, full-viewport height) — currently indistinguishable from agent session pages.

Design Token Quick Reference

The recommended palette is in token-reference.css. The current palette is in packages/web/src/app/globals.css.

Current base:      #0d1117  (GitHub blue-green dark)
Recommended base:  #0C0C11  (neutral blue-cast dark)

Current accent:    #58a6ff  (GitHub blue)
Recommended accent: #5B7EF8 (blue-indigo, between Linear blue and brand purple)

All Linear CSS values are ground-truth verified from live CSS. Railway values are visually estimated from screenshot. Other competitor values are from text/HTML analysis.