Trace

Trace is an enterprise support-to-engineering agent system. It turns a messy customer bug report into a reproduced browser failure, a constrained code fix, verified before/after evidence, and a GitHub issue plus pull request.

The demo is built for a common enterprise pain point: support teams receive high-impact UI bugs, but engineering often lacks the exact repro steps, environment, logs, screenshots, and confidence needed to act quickly. Trace compresses that handoff into one observable workflow.

• Multi-agent investigation with explicit dependencies instead of a flat agent animation.
• Live Cerebras + Gemma 4 31B reasoning for report triage, visual analysis, log analysis, source localization, patch planning, and maintainer handoff.
• Optional Gemini 3 Flash mode for running the same workflow through another live provider.
• Multimodal evidence across customer text, device metadata, screenshots, browser state, client logs, code diffs, and GitHub artifacts.
• Playwright-driven mobile repro at a 390x844 viewport.
• Deterministic patching through an allowlisted source edit.
• Verification screenshots before and after the fix.
• Real GitHub issue, branch, commit, and pull request creation for the target demo repo.

There are no canned model fallbacks. If the selected model provider is missing, returns invalid JSON, or fails, the workflow fails visibly.

The seeded customer report is:

Checkout button disappears on mobile after I apply my coupon.

Trace runs the following workflow:

1. Reset the target checkout app to the known buggy state.
2. Triage the report for severity, environment, and expected behavior.
3. Run Vision and Log agents in parallel after triage.
4. Drive a live browser repro with Playwright.
5. Create a bug report artifact from confirmed evidence.
6. Localize the likely source file and breakpoint-specific defect.
7. Ask the selected model for a constrained patch plan.
8. Apply only the allowlisted source edit.
9. Verify desktop and mobile behavior with Playwright.
10. Open or update a GitHub issue and PR with evidence.
11. Generate the maintainer handoff summary.

The controlled target bug is intentionally simple and visual: applying SAVE20 on mobile hides the checkout CTA, while desktop remains usable. The point of the project is not the bug itself; it is the verified support-to-engineering loop.

• / - Trace dashboard and fullscreen investigation workflow.
• /checkout - Customer-facing checkout app with the controlled mobile bug.
• /checkout/repro-frame - Narrow repro frame used by the live preview.

• /api/trace/workflow/run - Main Server-Sent Events investigation workflow.
• /api/trace/repro - Playwright desktop/mobile repro and screenshot capture.
• /api/trace/patch/plan - Live model patch-plan request.
• /api/trace/patch/apply - Allowlisted patch application and verification.
• /api/trace/patch/reset - Restores the known buggy target state.
• /api/trace/run - Legacy agent stream endpoint kept for debugging.
• /api/trace/speed - Optional live GPU baseline comparison endpoint.

• Node.js 20 or newer
• npm
• Chromium installed for Playwright
• A Cerebras API key for the primary demo path
• Optional Gemini API key for comparison mode
• GitHub authentication if you want Trace to open the issue and PR

Install dependencies:

npm install
npx playwright install chromium

Start the app:

npm run dev

Open:

http://localhost:3000

Create .env.local from .env.example.

Minimum Cerebras setup:

CEREBRAS_API_KEY=your-key
CEREBRAS_MODEL=gemma-4-31b

Optional custom Cerebras endpoint:

CEREBRAS_BASE_URL=https://api.cerebras.ai

Optional Gemini comparison mode:

GEMINI_API_KEY=your-key
GEMINI_MODEL=gemini-3-flash-preview

Optional live GPU baseline:

GPU_BASELINE_API_KEY=your-key
GPU_BASELINE_BASE_URL=https://api.example.com/v1
GPU_BASELINE_MODEL=your-model
GPU_BASELINE_PROVIDER_NAME=GPU provider

GitHub handoff authentication:

GITHUB_TOKEN=your-token

If GITHUB_TOKEN or GH_TOKEN is not set, Trace tries Git Credential Manager. The GitHub runtime currently targets divagr18/mobile-demo as the intentionally buggy downstream app used in the demo.

Run the standard checks:

npm run lint
npx tsc --noEmit
npm run build

Manual demo checks:

1. Open /checkout on desktop, apply SAVE20, and confirm the checkout button remains visible.
2. Open /checkout at mobile width, apply SAVE20, and confirm the checkout button disappears.
3. Open /, choose Cerebras, and click Run Investigation.
4. Confirm model-owned steps are labeled Cerebras live.
5. Confirm the workflow shows repro evidence, patch diff, before/after screenshots, and GitHub issue/PR artifacts.
6. Call /api/trace/patch/reset before recording another fresh run.

The checkout selectors are stable for automation:

• data-testid="coupon-input"
• data-testid="apply-coupon"
• data-testid="checkout-button"
• data-testid="cart-total"

Trace uses a small typed workflow runtime instead of a generic animation loop. Each step declares its dependencies, owner, runtime type, and artifact outputs. Only independent evidence steps run in parallel.

Core modules:

• src/lib/trace-workflow-runtime.ts - dependency-aware workflow executor.
• src/lib/workflow-definition.ts - visible investigation graph.
• src/lib/trace-agent-runtime.ts - Cerebras and Gemini model adapters.
• src/lib/repro-runtime.ts - Playwright repro and screenshot capture.
• src/lib/trace-patch-runtime.ts - allowlisted patch and verification loop.
• src/lib/github-pr-runtime.ts - issue, branch, evidence, and PR handoff.
• src/components/AgentSwarm.tsx - fullscreen investigation UI.
• src/components/CheckoutDemo.tsx - controlled target checkout app.

Trace is designed around latency-sensitive enterprise workflows. A support engineer should be able to click once and watch agents reason over the report, inspect evidence, reproduce the bug, plan a fix, verify it, and prepare the PR while the context is still fresh.

Cerebras speed makes the agent workflow feel interactive instead of becoming another asynchronous ticket queue.

Before recording a demo:

• Use a clean browser profile or incognito window.
• Hide notifications and unrelated browser tabs.
• Do not show .env, API keys, credentials, or private emails.
• Keep the recording focused on the Trace dashboard, live workflow, and GitHub PR evidence.

See VISION.md for the product thesis, completed stages, and 60-second demo script.