[Phase 5.4] PRD stress-test web UI: trigger and streaming progress

[frankbria]

Goal

Add a [Stress Test] button to the PRD page that triggers the stress-test pipeline and streams progress back to the browser.

Background

The CLI has cf prd stress-test for recursive decomposition — it surfaces ambiguities the agent cannot resolve without human input. Web-only users never see this step, skipping the most valuable part of the THINK phase.

Scope

• [Stress Test] button on the PRD page, enabled only when a PRD exists
• Clicking opens a modal or side panel with a streaming progress view (SSE or WebSocket)
• Backend: expose POST /api/v2/prd/stress-test that runs the existing cf prd stress-test core logic and streams intermediate results (decomposition steps)
• Loading/streaming state: show "Analyzing PRD..." with a spinner and incremental output lines as they arrive
• On completion: transition to results view (separate issue [Phase 5.4] PRD stress-test web UI: results view and PRD refinement #562)
• Error state: show error message with retry button

Out of scope

• Results rendering and answer flow (issue [Phase 5.4] PRD stress-test web UI: results view and PRD refinement #562)
• No UI changes to the PRD editor itself

Acceptance criteria

• [Stress Test] button is visible on the PRD page
• Clicking the button starts the stress-test and shows streaming output
• Backend endpoint calls core stress-test logic
• Error state handled gracefully
• npm test and uv run pytest pass

[coderabbitai]

🔗 Related PRs

#194 - Fix PRD generation progress tracking UI [merged]
#196 - fix(discovery): Synchronize PRD buttons and fix state persistence on tab revisit [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#317 - feat(cli): add interactive PRD generation via Socratic discovery [merged]
#446 - feat(prd): recursive decomposition stress test (#421) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• codeframe/core/prd_stress_test.py contains the complete headless stress_test_prd() orchestrator — it is synchronous and LLM-bound (many sequential provider.complete() calls), making it a natural fit for a streaming SSE endpoint that yields progress events as each goal is decomposed.
• codeframe/ui/routers/prd_v2.py already owns the /api/v2/prd prefix and uses get_v2_workspace + rate_limit_standard patterns consistently.
• codeframe/ui/routers/streaming_v2.py shows the established SSE pattern: StreamingResponse with text/event-stream, format_sse_event, and heartbeat comments.
• The frontend uses Dialog + ScrollArea from shadcn/ui (seen in PRDVersionHistoryModal), @hugeicons/react icons, Button, and axios-based prdApi in web-ui/src/lib/api.ts. The PRDHeader is the right place to add the new button.

Approach

Add a new SSE endpoint directly to prd_v2.py (keeping the /api/v2/prd prefix), wrap stress_test_prd() in an async generator that yields JSON-encoded progress events per decomposition step, and surface it in the frontend via a new StressTestModal component that opens from PRDHeader. This avoids new routers, new state managers, or WebSocket complexity — SSE is already the established streaming pattern in this codebase.

---

Implementation Plan

1. Extend the core stress-test engine with a streaming generator

In file:codeframe/core/prd_stress_test.py, add a new async generator function stress_test_prd_stream() that mirrors stress_test_prd() but yields a progress event dict after each significant step:

• After goal extraction → yield {"type": "goals_extracted", "goals": [...]}
• After each recursive_decompose() call for a top-level goal → yield {"type": "goal_analyzed", "goal": "<title>", "classification": "...", "ambiguities_so_far": N}
• On completion → yield {"type": "complete", "ambiguity_count": N, "tech_spec_markdown": "...", "ambiguity_report": "..."}
• On exception → yield {"type": "error", "message": "..."}

Because provider.complete() is synchronous and blocking, wrap each call with asyncio.to_thread() inside the generator so the FastAPI event loop is not blocked.

---

2. Add POST /api/v2/prd/stress-test SSE endpoint

In file:codeframe/ui/routers/prd_v2.py:

New Pydantic model:

StressTestRequest  (no body fields needed — PRD is fetched from workspace)

New endpoint — place it before the /{prd_id} routes to avoid path conflicts:

POST /api/v2/prd/stress-test

• Depends on get_v2_workspace and rate_limit_standard.
• Fetches the latest PRD via prd.get_latest(workspace) — returns 404 if none exists.
• Instantiates AnthropicProvider (same pattern as session_chat_ws.py).
• Returns a StreamingResponse with media_type="text/event-stream" and headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}.
• The inner async generator calls stress_test_prd_stream() and formats each yielded dict as data: <json>\n\n (matching format_sse_event style from streaming_v2.py). Also emits : heartbeat\n\n comments every ~15 s to prevent proxy timeouts.

Import AnthropicProvider lazily inside the endpoint function (same pattern as session_chat_ws.py) to avoid circular imports.

---

3. Add prdApi.startStressTest() to the frontend API client

In file:web-ui/src/lib/api.ts, add to the prdApi object:

startStressTest(workspacePath: string): EventSource

This method constructs the URL ${baseURL}/api/v2/prd/stress-test?workspace_path=... and returns a native browser EventSource. (Auth cookies are sent automatically via withCredentials; the SSE endpoint must accept cookie-based auth, consistent with how the task stream endpoint works.)

---

4. Add TypeScript types for stress-test SSE events

In file:web-ui/src/types/prd.ts, add:

export type StressTestEventType =
  | 'goals_extracted'
  | 'goal_analyzed'
  | 'complete'
  | 'error';

export interface StressTestGoalsExtractedEvent {
  type: 'goals_extracted';
  goals: string[];
}

export interface StressTestGoalAnalyzedEvent {
  type: 'goal_analyzed';
  goal: string;
  classification: 'atomic' | 'composite' | 'ambiguous';
  ambiguities_so_far: number;
}

export interface StressTestCompleteEvent {
  type: 'complete';
  ambiguity_count: number;
  tech_spec_markdown: string;
  ambiguity_report: string;
}

export interface StressTestErrorEvent {
  type: 'error';
  message: string;
}

export type StressTestEvent =
  | StressTestGoalsExtractedEvent
  | StressTestGoalAnalyzedEvent
  | StressTestCompleteEvent
  | StressTestErrorEvent;

Export these from file:web-ui/src/types/index.ts (or wherever prd.ts types are re-exported).

---

5. Create StressTestModal component

Create file:web-ui/src/components/prd/StressTestModal.tsx.

Model it after PRDVersionHistoryModal — use Dialog, DialogContent, DialogHeader, DialogTitle, ScrollArea, Button from the existing shadcn/ui imports, and Loading03Icon from @hugeicons/react.

Internal state machine:

'idle' → 'streaming' → 'complete' | 'error'

Props:

interface StressTestModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  workspacePath: string;
}

Behavior:

• When open becomes true, immediately call prdApi.startStressTest(workspacePath) to open the EventSource.
• Accumulate lines: string[] state — each incoming SSE event appends a human-readable line (e.g. "✓ Extracted 3 goals", "⚠ User Authentication — ambiguous", "✓ PDF Export — atomic").
• Show a spinner + "Analyzing PRD..." header while status === 'streaming'.
• Render lines in a ScrollArea with a <pre> or <div> that auto-scrolls to the bottom (use a useEffect + ref on the scroll container).
• On type === 'complete': transition to 'complete' state, show summary (ambiguity count), and a close button. Store tech_spec_markdown and ambiguity_report in state for issue [Phase 5.4] PRD stress-test web UI: results view and PRD refinement #562.
• On type === 'error': transition to 'error' state, show the error message and a Retry button that re-opens the EventSource.
• On onOpenChange(false) / unmount: close the EventSource to avoid leaks.

---

6. Wire StressTestModal into PRDHeader and PRDView

file:web-ui/src/components/prd/PRDHeader.tsx:

• Add onStressTest: () => void to PRDHeaderProps.
• Add a new Button (variant "outline", size "sm") between the History and Upload buttons, enabled only when prd !== null:
  • Icon: TestTube01Icon or FlaskIcon from @hugeicons/react (check availability; fall back to any suitable icon already imported in the project).
  • Label: Stress Test
  • disabled={!prd}

file:web-ui/src/components/prd/PRDView.tsx:

• Add onStressTest: () => void to PRDViewProps and thread it through to PRDHeader.

file:web-ui/src/app/prd/page.tsx:

• Add stressTestOpen state (useState(false)).
• Add handleStressTest handler that sets stressTestOpen(true).
• Pass onStressTest={handleStressTest} down through PRDView.
• Render <StressTestModal open={stressTestOpen} onOpenChange={setStressTestOpen} workspacePath={workspacePath} /> alongside the other modals.

file:web-ui/src/components/prd/index.ts:

• Export StressTestModal.

---

7. SSE authentication note

The existing task stream endpoint (GET /api/v2/tasks/{task_id}/stream) uses workspace_path query param only and relies on cookie-based auth (the axios client sets withCredentials: true). Follow the same pattern for the stress-test endpoint — no custom auth header needed for EventSource.

---

Data flow diagram

sequenceDiagram
    participant U as User (Browser)
    participant M as StressTestModal
    participant ES as EventSource
    participant API as POST /api/v2/prd/stress-test (SSE)
    participant Core as stress_test_prd_stream()
    participant LLM as AnthropicProvider

    U->>M: clicks [Stress Test]
    M->>ES: new EventSource(url)
    ES->>API: HTTP GET (SSE upgrade)
    API->>Core: start async generator
    Core->>LLM: extract_goals()
    LLM-->>Core: goals list
    Core-->>API: yield goals_extracted event
    API-->>ES: data: {"type":"goals_extracted",...}
    ES-->>M: onmessage → append line
    loop per top-level goal
        Core->>LLM: recursive_decompose()
        LLM-->>Core: node + ambiguities
        Core-->>API: yield goal_analyzed event
        API-->>ES: data: {"type":"goal_analyzed",...}
        ES-->>M: onmessage → append line
    end
    Core-->>API: yield complete event
    API-->>ES: data: {"type":"complete",...}
    ES-->>M: onmessage → show results
    M->>ES: close()

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `codeframe/core/prd_stress_test.py` contains the complete headless `stress_test_prd()` orchestrator — it is synchronous and LLM-bound (many sequential `provider.complete()` calls), making it a natural fit for a streaming SSE endpoint that yields progress events as each goal is decomposed.
- `codeframe/ui/routers/prd_v2.py` already owns the `/api/v2/prd` prefix and uses `get_v2_workspace` + `rate_limit_standard` patterns consistently.
- `codeframe/ui/routers/streaming_v2.py` shows the established SSE pattern: `StreamingResponse` with `text/event-stream`, `format_sse_event`, and heartbeat comments.
- The frontend uses `Dialog` + `ScrollArea` from shadcn/ui (seen in `PRDVersionHistoryModal`), `@hugeicons/react` icons, `Button`, and `axios`-based `prdApi` in `web-ui/src/lib/api.ts`. The `PRDHeader` is the right place to add the new button.

## Approach

Add a new SSE endpoint directly to `prd_v2.py` (keeping the `/api/v2/prd` prefix), wrap `stress_test_prd()` in an async generator that yields JSON-encoded progress events per decomposition step, and surface it in the frontend via a new `StressTestModal` component that opens from `PRDHeader`. This avoids new routers, new state managers, or WebSocket complexity — SSE is already the established streaming pattern in this codebase.

---

## Implementation Plan

### 1. Extend the core stress-test engine with a streaming generator

In `file:codeframe/core/prd_stress_test.py`, add a new async generator function `stress_test_prd_stream()` that mirrors `stress_test_prd()` but `yield`s a progress event dict after each significant step:

- After goal extraction → yield `{"type": "goals_extracted", "goals": [...]}` 
- After each `recursive_decompose()` call for a top-level goal → yield `{"type": "goal_analyzed", "goal": "<title>", "classification": "...", "ambiguities_so_far": N}`
- On completion → yield `{"type": "complete", "ambiguity_count": N, "tech_spec_markdown": "...", "ambiguity_report": "..."}`
- On exception → yield `{"type": "error", "message": "..."}`

Because `provider.complete()` is synchronous and blocking, wrap each call with `asyncio.to_thread()` inside the generator so the FastAPI event loop is not blocked.

---

### 2. Add `POST /api/v2/prd/stress-test` SSE endpoint

In `file:codeframe/ui/routers/prd_v2.py`:

**New Pydantic model:**
```
StressTestRequest  (no body fields needed — PRD is fetched from workspace)
```

**New endpoint** — place it before the `/{prd_id}` routes to avoid path conflicts:

```
POST /api/v2/prd/stress-test
```

- Depends on `get_v2_workspace` and `rate_limit_standard`.
- Fetches the latest PRD via `prd.get_latest(workspace)` — returns 404 if none exists.
- Instantiates `AnthropicProvider` (same pattern as `session_chat_ws.py`).
- Returns a `StreamingResponse` with `media_type="text/event-stream"` and `headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"}`.
- The inner async generator calls `stress_test_prd_stream()` and formats each yielded dict as `data: <json>\n\n` (matching `format_sse_event` style from `streaming_v2.py`). Also emits `: heartbeat\n\n` comments every ~15 s to prevent proxy timeouts.

Import `AnthropicProvider` lazily inside the endpoint function (same pattern as `session_chat_ws.py`) to avoid circular imports.

---

### 3. Add `prdApi.startStressTest()` to the frontend API client

In `file:web-ui/src/lib/api.ts`, add to the `prdApi` object:

```
startStressTest(workspacePath: string): EventSource
```

This method constructs the URL `${baseURL}/api/v2/prd/stress-test?workspace_path=...` and returns a native browser `EventSource`. (Auth cookies are sent automatically via `withCredentials`; the SSE endpoint must accept cookie-based auth, consistent with how the task stream endpoint works.)

---

### 4. Add TypeScript types for stress-test SSE events

In `file:web-ui/src/types/prd.ts`, add:

```typescript
export type StressTestEventType =
  | 'goals_extracted'
  | 'goal_analyzed'
  | 'complete'
  | 'error';

export interface StressTestGoalsExtractedEvent {
  type: 'goals_extracted';
  goals: string[];
}

export interface StressTestGoalAnalyzedEvent {
  type: 'goal_analyzed';
  goal: string;
  classification: 'atomic' | 'composite' | 'ambiguous';
  ambiguities_so_far: number;
}

export interface StressTestCompleteEvent {
  type: 'complete';
  ambiguity_count: number;
  tech_spec_markdown: string;
  ambiguity_report: string;
}

export interface StressTestErrorEvent {
  type: 'error';
  message: string;
}

export type StressTestEvent =
  | StressTestGoalsExtractedEvent
  | StressTestGoalAnalyzedEvent
  | StressTestCompleteEvent
  | StressTestErrorEvent;
```

Export these from `file:web-ui/src/types/index.ts` (or wherever `prd.ts` types are re-exported).

---

### 5. Create `StressTestModal` component

Create `file:web-ui/src/components/prd/StressTestModal.tsx`.

Model it after `PRDVersionHistoryModal` — use `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `ScrollArea`, `Button` from the existing shadcn/ui imports, and `Loading03Icon` from `@hugeicons/react`.

**Internal state machine:**

```
'idle' → 'streaming' → 'complete' | 'error'
```

**Props:**
```typescript
interface StressTestModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  workspacePath: string;
}
```

**Behavior:**

- When `open` becomes `true`, immediately call `prdApi.startStressTest(workspacePath)` to open the `EventSource`.
- Accumulate `lines: string[]` state — each incoming SSE event appends a human-readable line (e.g. `"✓ Extracted 3 goals"`, `"⚠ User Authentication — ambiguous"`, `"✓ PDF Export — atomic"`).
- Show a spinner + `"Analyzing PRD..."` header while `status === 'streaming'`.
- Render lines in a `ScrollArea` with a `<pre>` or `<div>` that auto-scrolls to the bottom (use a `useEffect` + `ref` on the scroll container).
- On `type === 'complete'`: transition to `'complete'` state, show summary (ambiguity count), and a close button. Store `tech_spec_markdown` and `ambiguity_report` in state for issue #562.
- On `type === 'error'`: transition to `'error'` state, show the error message and a **Retry** button that re-opens the `EventSource`.
- On `onOpenChange(false)` / unmount: close the `EventSource` to avoid leaks.

---

### 6. Wire `StressTestModal` into `PRDHeader` and `PRDView`

**`file:web-ui/src/components/prd/PRDHeader.tsx`:**

- Add `onStressTest: () => void` to `PRDHeaderProps`.
- Add a new `Button` (variant `"outline"`, size `"sm"`) between the History and Upload buttons, enabled only when `prd !== null`:
  - Icon: `TestTube01Icon` or `FlaskIcon` from `@hugeicons/react` (check availability; fall back to any suitable icon already imported in the project).
  - Label: `Stress Test`
  - `disabled={!prd}`

**`file:web-ui/src/components/prd/PRDView.tsx`:**

- Add `onStressTest: () => void` to `PRDViewProps` and thread it through to `PRDHeader`.

**`file:web-ui/src/app/prd/page.tsx`:**

- Add `stressTestOpen` state (`useState(false)`).
- Add `handleStressTest` handler that sets `stressTestOpen(true)`.
- Pass `onStressTest={handleStressTest}` down through `PRDView`.
- Render `<StressTestModal open={stressTestOpen} onOpenChange={setStressTestOpen} workspacePath={workspacePath} />` alongside the other modals.

**`file:web-ui/src/components/prd/index.ts`:**

- Export `StressTestModal`.

---

### 7. SSE authentication note

The existing task stream endpoint (`GET /api/v2/tasks/{task_id}/stream`) uses `workspace_path` query param only and relies on cookie-based auth (the axios client sets `withCredentials: true`). Follow the same pattern for the stress-test endpoint — no custom auth header needed for `EventSource`.

---

### Data flow diagram

```mermaid
sequenceDiagram
    participant U as User (Browser)
    participant M as StressTestModal
    participant ES as EventSource
    participant API as POST /api/v2/prd/stress-test (SSE)
    participant Core as stress_test_prd_stream()
    participant LLM as AnthropicProvider

    U->>M: clicks [Stress Test]
    M->>ES: new EventSource(url)
    ES->>API: HTTP GET (SSE upgrade)
    API->>Core: start async generator
    Core->>LLM: extract_goals()
    LLM-->>Core: goals list
    Core-->>API: yield goals_extracted event
    API-->>ES: data: {"type":"goals_extracted",...}
    ES-->>M: onmessage → append line
    loop per top-level goal
        Core->>LLM: recursive_decompose()
        LLM-->>Core: node + ambiguities
        Core-->>API: yield goal_analyzed event
        API-->>ES: data: {"type":"goal_analyzed",...}
        ES-->>M: onmessage → append line
    end
    Core-->>API: yield complete event
    API-->>ES: data: {"type":"complete",...}
    ES-->>M: onmessage → show results
    M->>ES: close()
```

---

Execution Information

Branch: main
Commit: 3f14270

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.