Release v0.3.151

fix: rename sessions from the chat rail

.github/automation.meta.json

@@ -3,7 +3,7 @@
   "stack": "claude",
   "profile": "sdk",
   "mode": "hub",
-  "hubRef": "v1.1.8",
+  "hubRef": "v1.1.11",
   "templateVersion": "1.1.7",
   "installedAt": "2026-09-07T10:02:11Z"
 }

.github/workflows/auto-pr-comment.yml

@@ -10,7 +10,7 @@ on:
   pull_request_target:
     types: [opened, synchronize]
   schedule:
-    - cron: '30 3,9,15,21 * * *'
+    - cron: '30 * * * *'
   workflow_dispatch:
 
 env:
@@ -27,7 +27,7 @@ jobs:
     permissions:
       issues: write
       pull-requests: write
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].10
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].20
     secrets: inherit
     with:
-      hub_ref: v1.1.10
+      hub_ref: v1.1.20

.github/workflows/bot-pr-recovery.yml

@@ -16,8 +16,8 @@ permissions:
 
 jobs:
   recover:
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].10
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].20
     secrets: inherit
     with:
-      hub_ref: v1.1.10
+      hub_ref: v1.1.20
       pr_number: ${{ github.event.inputs.pr_number || '' }}

.github/workflows/ci-failure-claude.yml

@@ -25,8 +25,8 @@ permissions:
 
 jobs:
   detect-and-trigger:
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].10
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].20
     secrets: inherit
     with:
-      hub_ref: v1.1.10
+      hub_ref: v1.1.20
       pr_number: ${{ github.event.inputs.pr_number || '' }}

.github/workflows/ci.yml

@@ -36,6 +36,30 @@ jobs:
       - name: Integration smoke tests
         run: pytest tests/integration/test_agentic_roundtrip.py tests/test_feature_sdk_backends.py -q --no-cov --timeout=120
 
+  frontend:
+    name: frontend
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: src/frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: src/frontend
+
+      # `npm run build` is the dashboard ship path: dist/ is synced to
+      # src/praisonaiui/templates/frontend/ (see src/frontend/README.md).
+      - name: Build frontend
+        run: npm run build
+        working-directory: src/frontend
+
   docs:
     runs-on: ubuntu-latest
     if: github.ref == 'refs/heads/main'

.github/workflows/claude-merge-gate.yml

@@ -43,9 +43,9 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v4
-      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].10
+      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].20
         with:
-          hub_ref: v1.1.10
+          hub_ref: v1.1.20
       - name: Generate GitHub App token
         id: app-token
         uses: actions/create-github-app-token@v1
@@ -87,9 +87,10 @@ jobs:
       issues: write
       actions: read
       id-token: write
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
+      statuses: write   # the assess job records security/outsider-review
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected]
     secrets: inherit
     with:
-      hub_ref: v1.1.10
+      hub_ref: v1.1.20
       pr_number: ${{ github.event.inputs.pr_number || github.event.client_payload.pr_number || '' }}
       merge_method: ${{ github.event.inputs.merge_method || 'merge' }}

.github/workflows/claude.yml

@@ -18,7 +18,7 @@ jobs:
       issues: write
       actions: read
       id-token: write
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].10
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].20
     secrets: inherit
     with:
-      hub_ref: v1.1.10
+      hub_ref: v1.1.20

.github/workflows/merge-conflict-claude.yml

@@ -25,9 +25,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].10
+      - uses: MervinPraison/github-automation-template/.github/actions/[email protected].20
         with:
-          hub_ref: v1.1.10
+          hub_ref: v1.1.20
       - name: Detect conflicting PRs and trigger Claude
         uses: actions/github-script@v7
         with:

.github/workflows/pipeline-status-sync.yml

@@ -13,7 +13,7 @@ permissions:
 
 jobs:
   sync:
-    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].10
+    uses: MervinPraison/github-automation-template/.github/workflows/[email protected].20
     secrets: inherit
     with:
-      hub_ref: v1.1.10
+      hub_ref: v1.1.20

README.md

@@ -366,3 +366,7 @@ pytest tests -v
 ## License
 
 MIT © [Praison Limited](https://praison.ai)
+
+Third-party vendored source is documented in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+See the [BeautifulUI upgrade playbook](docs/frontend/beautifului.md) for how BeautifulUI
+primitives are vendored and pinned.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,43 @@
+# Third-Party Notices
+
+PraisonAIUI incorporates or vendors source from the third-party projects listed below.
+Their licences and copyright notices are retained here as required.
+
+---
+
+## BeautifulUI
+
+- Project: BeautifulUI — <https://www.beautifului.dev/>
+- Source: <https://github.com/slev12397/beautiful-ui>
+- Licence: MIT
+
+BeautifulUI is distributed as a shadcn registry / copy-paste library (no npm package).
+When its React primitives are vendored into `src/frontend`, the following MIT licence
+applies to that copied source.
+
+```
+MIT License
+
+Copyright (c) Shane Levine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+See the upgrade playbook at [`docs/frontend/beautifului.md`](docs/frontend/beautifului.md)
+for how BeautifulUI is vendored and pinned.

aiui.template.yaml

@@ -59,6 +59,11 @@ navigation:
             - typescript/runtime
             - typescript/nextjs
             - typescript/components
+        - group: "Frontend"
+          icon: "layout"
+          prefix: "frontend"
+          pages:
+            - frontend/beautifului
         - group: "Examples"
           icon: "folder-open"
           prefix: "examples"

docs/adr/0001-replay-view-clean-room.md

@@ -0,0 +1,94 @@
+# ADR 0001: PraisonAI Replay view, a clean-room design
+
+- **Status:** accepted
+- **Date:** 2026-10-26
+- **Scope:** `src/praisonaiui/features/replay.py`, `features/_trace_jsonl.py`,
+  `templates/frontend/plugins/views/replay-core.js`, `templates/frontend/plugins/views/replay.js`
+
+## Context
+
+PraisonAI records agent runs as context-trace JSONL (one `ContextEvent.to_dict()` per
+line). People need to see what a team or flow did: who did what, when, why, and at what
+cost, both after the fact and live. Other tools have shown that a graph plus a trace is a
+useful way to look at agent runs. We want that value without copying anyone's product,
+code or look, and without adding dependencies.
+
+## Decision
+
+Build our own view, in plain DOM and SVG, with our own layout code, palette and words.
+
+### Ideas we took (ideas only)
+
+| Idea | Where it came from | What we did with it |
+|---|---|---|
+| Show the graph of a multi-agent program next to the trace of a run | The general concept behind LangGraph Studio's graph-plus-trace view, known from public talks and articles | A **Map** view drawn by our own layered layout (`layoutMap`); the default view is a **Timeline**, which Studio does not have |
+| Parallel voices on shared time, read left to right | Musical scores and swimlane diagrams | One lane per agent plus Manager and You; parallel branches as sub-lanes; tasks and steps as "chapters" across the top |
+| Vocabulary for LLM and tool spans, tokens and cost | OpenTelemetry GenAI semantic conventions (public specification) | Block kinds (LLM, tool), token and cost totals; the wrapper's OTLP export uses the conventions, the UI only borrows the concepts |
+
+### What we did not use
+
+- **No third-party UI code, CSS, icons, layouts or screenshots** were used to build this
+  view. Shapes, palette, spacing, wording ("Brief", "Delivered", "Waiting for you") and
+  the layout algorithm are our own.
+- **LangGraph's server (Elastic License 2.0) and the proprietary LangGraph Studio were
+  not consulted for code**, and none of their assets, markup or styles were copied. We
+  do not use the name "Studio", any "Lang…" naming, or `__start__`/`__end__` pills.
+- No Mermaid, D3, React Flow, dagre, ELK or other graph libraries. The dashboard's
+  existing Mermaid CDN plugin is not used by Replay.
+
+### How it is built
+
+- `replay-core.js`: pure functions (`buildModel`, `narrate`, `layoutMap`,
+  `deriveGraph`). No DOM, no network. Tested with `node --test`.
+- `replay.js`: DOM/SVG rendering, keyboard handling, SSE follow and approvals. It also
+  boots by itself when `window.__REPLAY_DATA__ = {events, graph}` is set, which is how
+  the wrapper's single-file HTML export works (`standalone_html()` inlines both files).
+- `layoutMap` is a textbook layered layout written from scratch: depth-first search to
+  find back edges (loops), longest-path layering, one virtual waypoint per crossed layer
+  for long edges, and a few barycentre sweeps to order each layer. It is deterministic.
+- Narration is template text, chosen per event type. No LLM, no randomness.
+
+## Palette and accessibility rationale
+
+| Role | Fill | Shape | Why |
+|---|---|---|---|
+| Agent | `#8B0000` | circle | PraisonAI's brand red; white text on it is 10.0:1 |
+| Tool | `#0F7287` | rounded rectangle | Teal kept from the brand but darkened from `#189AB4` (white text on `#189AB4` fails AA); white on `#0F7287` is 5.6:1 |
+| You (human) | `#8A5A00` | diamond | Amber distinct from red and teal for common colour-vision deficiencies; white on it is 5.9:1 |
+| Manager | `#3C4A5C` | square | Neutral slate, so the manager reads as coordination, not work; white on it is 9.0:1 |
+
+- **Never colour alone.** Every lane, block, node and step has a shape and a text label;
+  arrows differ by dash pattern and carry words ("hands off", "delegates", "routes").
+  Heat in the cost/latency overlay is a bar whose height and shade both grow, plus the
+  value in text.
+- **Theme.** Follows the system setting (`prefers-color-scheme`) by default, with a
+  Light/Dark override; the light theme is the design baseline.
+- **Light theme first.** Text tokens are at least 6.9:1 on their backgrounds in light mode
+  and 7.7:1 in dark mode. In dark mode the palette fills keep white text at AA, and get a
+  light 2 px outline so each shape's boundary stays above 3:1 against the dark page.
+- **Keyboard throughout.** ← → (and ↑ ↓ in the step list) move the replay cursor, Home
+  and End jump to the ends, tabs follow the ARIA tabs pattern, map nodes use a roving
+  tab stop, and every action has a real button.
+- **Screen readers.** The narration column is a real ordered list and is the main way
+  through a run. Timeline blocks and map nodes are named buttons whose names start with
+  their visible text (WCAG 2.5.3). Live updates are announced through a polite live
+  region, throttled.
+- **Motion.** The only animation (the live dot) runs only under
+  `prefers-reduced-motion: no-preference`; scrolling is instant when motion is reduced.
+- Checked with axe-core against WCAG 2.0, 2.1 and 2.2 A/AA in both themes (dev-only test
+  in `tests/browser/`).
+
+## Dependency licences
+
+No new runtime or build dependencies. The Python side uses only the standard library and
+Starlette, which aiui already depends on. The browser side is plain ES modules with no
+imports beyond our own file. Dev-only test tools that are not shipped: Playwright
+(Apache-2.0, already used in this environment) and axe-core (MPL-2.0, loaded from a path
+given by `AXE_CORE_JS`; not vendored).
+
+## Consequences
+
+- We own the look and the layout code, and can change them without licence questions.
+- The layout is simpler than a dedicated graph engine. It is fine for the team and flow
+  sizes we see (tens of nodes). Very large graphs may need a better crossing-reduction
+  step later.

docs/features/beautifului-integration.md

@@ -0,0 +1,56 @@
+# BeautifulUI Integration Strategy
+
+> **Epic:** [#292](https://github.com/MervinPraison/PraisonAIUI/issues/292) — BeautifulUI integration strategy for AI-native dashboard UX.
+> This is the durable, agreed strategy that the linked child issues execute against.
+
+[BeautifulUI](https://www.beautifului.dev/) (MIT, Shane Levine / Turbo) is a **copy-paste / shadcn-registry** library of React primitives for AI-native interfaces: thinking traces, streaming answers with inline sources, HITL approval cards, tool chips, task rows, context chunks, diff/records tables, prompt bars, and a reference chat harness.
+
+There is **no published npm package** named `beautiful-ui`. It ships only as source consumed via the shadcn registry or manual copy.
+
+## 1. Strategic decision
+
+BeautifulUI is adopted as **vendored source**, not a runtime dependency, and is exposed to dashboard plugins **only through the existing `@praisonaiui/react` package** — never by importing upstream file paths directly. Rollout is **phased behind a feature flag**, keeping the current vanilla dashboard as the fallback until parity is proven.
+
+Upstream stack (Next.js 15 · React 19 · Tailwind v4 · TypeScript) is closely aligned with PraisonAIUI's `src/frontend` (Vite · React 19 · Tailwind v4 · shadcn/Radix), so primitives port with adapter work rather than a runtime bridge.
+
+## 2. Pillars
+
+| # | Pillar | Decision |
+|---|--------|----------|
+| 1 | **Vendoring model** | Add primitives into `src/frontend` via `npx shadcn add https://www.beautifului.dev/r/<component>.json`, or manual copy from [github.com/slev12397/beautiful-ui](https://github.com/slev12397/beautiful-ui). Pin via lockfile plus a recorded registry URL / git SHA. No `beautiful-ui` npm dependency in production builds. |
+| 2 | **Adapter layer** | Map PraisonAIUI chat / approval / trace **protocol events** to stable internal props. Primitives sit behind `@praisonaiui/react` exports; dashboard plugins consume those exports, not upstream paths. See [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294). |
+| 3 | **Hybrid rollout** | Mount React **islands** (or expand `@praisonaiui/react`) for high-value surfaces first — chat streaming/thinking/tools, then approvals. Vanilla chat (`templates/frontend/plugins/views/chat.js`) stays as the flag-gated fallback until parity is proven. |
+| 4 | **Token strategy** | Merge BeautifulUI foundation CSS **selectively** into the existing shadcn theme generation (`praisonaiui/themes.py`). One design system per page — avoid two competing token sets. |
+| 5 | **Icon licence** | Upstream `SidebarNav` uses the paid `@central-icons-react`. Port nav patterns with **lucide-react** (already in PraisonAIUI) instead. |
+
+## 3. Phasing
+
+1. **Spike** — evaluate primitives in the dev environment, confirm React 19 / Tailwind v4 alignment. [#293](https://github.com/MervinPraison/PraisonAIUI/issues/293)
+2. **Architecture** — adapter layer + upstream pin policy. [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294)
+3. **CI gate** — frontend build + BeautifulUI compatibility check (no frontend build gate exists today). [#295](https://github.com/MervinPraison/PraisonAIUI/issues/295)
+4. **Migrations** — chat streaming / thinking / tool chips ([#296](https://github.com/MervinPraison/PraisonAIUI/issues/296)), then the approval card ([#297](https://github.com/MervinPraison/PraisonAIUI/issues/297)).
+5. **Docs** — upgrade playbook + MIT attribution. [#298](https://github.com/MervinPraison/PraisonAIUI/issues/298)
+
+## 4. Risks
+
+| Risk | Mitigation |
+|------|------------|
+| No semver npm package | Vendor the source; pin to a recorded registry URL / git SHA in the lockfile. |
+| Upstream breaking registry JSON | Vendoring decouples builds from live registry; re-sync is a deliberate, reviewed step. |
+| Icon licence (`@central-icons-react` is paid) | Use lucide-react for ported nav patterns; never vendor the paid package. |
+| Two competing design systems on one page | Selective CSS token merge into `themes.py`; adapter-only prop surface. |
+| React / Tailwind drift | Upstream (React 19 / Tailwind v4) already matches `src/frontend`; the CI gate catches drift. |
+
+## 5. Out of scope
+
+- Replacing the entire dashboard shell in one PR.
+- PyPI packaging of BeautifulUI.
+- iframe embedding of beautifului.dev.
+- Depending on any unpublished npm package for production builds.
+
+## 6. Acceptance criteria status
+
+- [x] Written integration strategy agreed (vendoring + adapter + phased rollout) — this document.
+- [x] Risks documented — section 4.
+- [x] Child issues filed and prioritised — [#293](https://github.com/MervinPraison/PraisonAIUI/issues/293)–[#298](https://github.com/MervinPraison/PraisonAIUI/issues/298).
+- [x] No requirement to depend on unpublished npm packages for production builds — pillar 1, out of scope.

docs/features/replay.md

@@ -0,0 +1,176 @@
+# Replay
+
+**PraisonAI Replay** shows a recorded agent run as a story: who did what, when, why, and
+at what cost. It works for finished runs and for runs that are still going.
+
+## Record a run, then open it
+
+```bash
+praisonai replay view agents.yaml      # records the run and opens Replay on it
+```
+
+or from Python:
+
+```python
+from praisonai.replay import record
+
+with record(live=True):
+    team.start()
+```
+
+Every recorded run is a file `<id>.jsonl` in the traces folder. Replay reads it from
+`$PRAISONAI_TRACES_DIR`, else `$PRAISON_HOME/traces`, else `~/.praison/traces`.
+
+To open aiui on Replay yourself:
+
+```bash
+aiui run "$(python -c 'import praisonaiui.replay_app as m; print(m.__file__)')" \
+    --style dashboard --host 127.0.0.1 --port 8090
+# then open http://127.0.0.1:8090/replay?run=<id>
+```
+
+`/#/replay?run=<id>` works too. In a full dashboard, Replay is in the sidebar under
+**Control**.
+
+## Watch a run live: the Run button
+
+For learning, demos and debugging, open a page with a **Run** button. Each click records
+a new run, and the page draws it as it happens:
+
+```python
+from praisonai.replay import watch
+
+watch(flow, input="solar sails")   # an Agent, AgentTeam, AgentFlow or agents.yaml
+```
+
+```bash
+praisonai replay watch agents.yaml
+```
+
+On the **Map**, each step and agent shows where the run is: dashed means not reached,
+blue (pulsing) means running now, green means done and red means failed. After a run,
+**▶ Play** moves through it again one step at a time, and the map rewinds with it. One
+run goes at a time. Each run of a team starts its tasks afresh; an Agent keeps its chat
+history between runs.
+
+## Show progress inside your own app
+
+`create_replay_app()` is the same view as a small ASGI app, without the dashboard. Mount
+it in any FastAPI or Starlette app:
+
+```python
+from praisonai.replay import record, replay_app
+
+app.mount("/replay", replay_app())         # read-only: shows recorded runs
+
+# wherever your app starts work:
+with record(run_id, live=True):
+    team.start()
+```
+
+Then show one run, live, in your page, for example in an `<iframe>`:
+
+```html
+<iframe src="/replay/?run=RUN_ID" style="width:100%;height:640px"></iframe>
+```
+
+| URL | Shows |
+|---|---|
+| `/replay/` | The run list and the selected run |
+| `/replay/?run=<id>` | Only that run, no list. A run that has not started yet is waited for. |
+
+`replay_app(team)` adds the Run box to the mounted page. Without the PraisonAI wrapper,
+pass any `run(input, run_id)` callable to `praisonaiui.features.replay.create_replay_app`;
+it must record the run under `run_id`. For a page you build yourself, the view is one
+module:
+
+```html
+<div id="progress"></div>
+<script type="module">
+  import { render } from "/replay/replay.js";
+  render(document.getElementById("progress"), { base: "/replay", run: "RUN_ID", approve: false });
+</script>
+```
+
+`render()` options: `base` (where the API is mounted), `run` (show only this run),
+`runner` (`{input, placeholder, ask}` to show the Run box) and `approve` (`false` hides
+the approve and deny buttons; the embedded app has no approvals API, so answer approvals
+where your app asks for them).
+
+Anyone who can reach the mounted app can read the runs, and with a runner can start one.
+Keep it on localhost or behind your app's login. `POST /api/replay/run` only accepts
+`Content-Type: application/json`, so another website cannot start a run from a visitor's
+browser.
+
+## What you see
+
+| Part | What it shows |
+|---|---|
+| **Runs** | Recorded runs, newest first. A run that is still being written has a **Live** badge. |
+| **Timeline** (default) | One lane per agent, plus **Manager** and **You**. Time runs left to right. LLM calls and tool calls are blocks in their agent's lane. Arrows show hand-offs, delegation, routing and approval requests. Parallel branches get their own sub-lanes. A call or step repeated back to back is one block marked ×N. Tasks and steps run across the top. |
+| **Map** | The team or flow as a graph, drawn from the graph recorded at the start of the run and fitted to the page (−, Fit and + zoom; drag to pan). Agents that took part but are not in the graph, for example after a hand-off to an agent outside the team, appear in an **Outside the team** group with their hand-offs. Older recordings without a graph get a "who talked to whom" map built from the events. Each node shows its state at the cursor: dashed means not reached, blue means running, green means done (×N when it ran more than once) and red means failed; the node the cursor is on has a bold outline. |
+| **What happened** | One plain sentence per step, for example *"Researcher asked web_search for 'solar sail facts' — 1.2 s, $0.002."* Hovering or focusing a sentence highlights its block, and the other way round. |
+| **Details** | Three tabs for the selected step. **What happened**: when, who, how long, cost, tokens, output. **Why**: only what the recording holds, such as the input given to a tool, the context passed in a hand-off and its reason, the manager's task snapshot, the route a step chose, and an approval's decision and where an automatic approval came from. **Raw JSON**: the events themselves. |
+| **Cost & latency** | Adds a bar under each block (taller and darker means more cost, or more time) and per-agent totals in the lane labels. |
+
+Shapes always carry meaning as well as colour: agents are circles, tools are rounded
+rectangles, you are a diamond and the manager is a square. In each lane, LLM calls sit on
+the top row and that agent's tool calls on a thinner row under them, so a long LLM call
+never hides its tools. Labels that do not fit end in "…"; hover or focus a block to see the
+whole label.
+
+The **Theme** menu follows your system's light or dark setting by default; choose Light or
+Dark to override it. On a phone the run list, timeline and steps stack in one column.
+
+## Moving through a run
+
+Replay opens at the end of the run, so you see everything. Move the cursor to replay it:
+anything after the cursor is drawn as an outline.
+
+| Key | Action |
+|---|---|
+| ← → | Previous / next step |
+| ↑ ↓ | Previous / next step in the step list; previous / next node in the map |
+| Home / End | First / last step |
+| Enter or Space | Open the focused block or node |
+| ← → in the tabs | Switch between What happened, Why and Raw JSON |
+
+The scrubber under the timeline does the same with a mouse or touch, and **▶ Play** steps
+through on its own. On a live run the
+cursor follows new events; if you step back, **Jump to live** takes you to the latest.
+
+## Approving from Replay
+
+When an agent asks for approval and the run uses aiui's approval store, a **Waiting for
+you** card appears above the timeline:
+
+- **Approve** or **Deny**, with an optional reason.
+- **Edit arguments…** opens the arguments as JSON (taken from the server, not the redacted
+  recording when the server has them). The JSON must be an object; mistakes are shown
+  as you type. **Approve with these arguments** sends them as `modified_args`.
+
+These buttons call `POST /api/approvals/{id}/approve` and `/deny`. The agent waits until
+you answer, and is denied if nobody answers before the approval timeout.
+
+## Sharing a run as one file
+
+`praisonai replay export RUN --format html` writes a single HTML file with the run and
+this viewer inside. It needs no server and no network. Approvals cannot be answered from
+an exported file.
+
+## HTTP API
+
+| Endpoint | Returns |
+|---|---|
+| `GET /api/replay/runs` | `[{run_id, session_id, path, started_at, ended_at?, status, kind, name, agents, events, cost_usd, live}]`, newest first |
+| `GET /api/replay/runs/{id}/events?after_seq=N` | `{events, graph, run}`; `after_seq` keeps only events with a larger `sequence_num`; `wait=1` answers `{events: [], graph: null, run: null}` instead of 404 for a run that has not started yet |
+| `GET /api/replay/runs/{id}/stream` | Server-sent events: `event: ctx` per trace event (with `id:` = `sequence_num`), `ping` every 15 s, `end` once the run has finished and gone quiet for 2 s. Honours `after_seq` and `Last-Event-ID`. |
+
+With a runner (`create_replay_app(run=...)`), `POST /api/replay/run` with
+`{"input": "..."}` starts a run and returns `{run_id}` (409 while one is going).
+
+Run ids must match `^[A-Za-z0-9._-]+$`. Replay never writes trace files itself. Half-written last lines, unknown fields and unknown event types are skipped
+safely, and schema 1.0 recordings still open.
+
+The **Traces** page reads the same files: each run is a trace, and its spans come from
+matching start and end events.

docs/frontend/BEAUTIFULUI_UPSTREAM.md

@@ -0,0 +1,35 @@
+# BeautifulUI upstream pin record
+
+BeautifulUI is vendored (shadcn-style registry copy), **not** an npm dependency.
+This file is the single source of truth for what upstream revision is vendored.
+Update it in the **same PR** that adds or bumps any vendored component, and make
+sure the frontend CI gate (issue #295) passes.
+
+See [beautifului-adapter-architecture.md](./beautifului-adapter-architecture.md)
+for the adapter boundary and folder layout.
+
+## Pin
+
+| Field | Value |
+|-------|-------|
+| Upstream repo | _TBD — record on first vendor_ |
+| Git SHA | _TBD_ |
+| Vendored on (date) | _TBD_ |
+| Registry base URL | _TBD_ |
+| License | MIT (kept in-tree) |
+
+## Vendored components
+
+Record one row per component the first time it is copied in.
+
+| Component | Registry URL | SHA | Vendored path | Date |
+|-----------|--------------|-----|---------------|------|
+| _(none yet)_ | | | | |
+
+## Upgrade checklist
+
+1. Update the SHA / date / registry rows above.
+2. Re-copy changed components into `src/frontend/src/agent-ui/vendors/beautifului/`.
+3. Keep all upstream imports inside `src/agent-ui/` (adapter boundary rule).
+4. Run the frontend build + adapter unit tests (frontend CI gate, #295).
+5. Do **not** add a `beautiful-ui` entry to `package.json` dependencies.

docs/frontend/beautifului-adapter-architecture.md

@@ -0,0 +1,102 @@
+# ADR: BeautifulUI adapter layer & upstream pin policy
+
+**Status:** Accepted · **Issue:** [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294)
+
+## Context
+
+BeautifulUI is **not** a semver npm library — it is distributed as shadcn-style
+registry components that are copied into the consuming repo. PraisonAIUI must
+integrate it without leaking upstream types or import paths across the codebase,
+and without breaking when either side updates.
+
+## Decision
+
+Introduce a single **adapter boundary** between transport payloads and the UI,
+and vendor BeautifulUI components behind that boundary.
+
+```
+Agent APIs (Python) ──► event bus / WS messages
+                              │
+                              ▼
+                    Agent-UI adapter (src/agent-ui/adapter.ts)
+                    (stable PraisonAIUI contracts)
+                              │
+                              ▼
+              @praisonaiui/react re-exports
+              (BeautifulUI vendored components)
+                              │
+                              ▼
+         Dashboard / chat mount points (React islands, then full shell)
+```
+
+### 1. Folder layout
+
+```
+src/frontend/src/agent-ui/
+├── contracts.ts        # Stable PraisonAIUI view models (the ONLY types consumers import)
+├── adapter.ts          # Pure mappers: wire payload -> contracts
+├── adapter.test.ts     # Unit tests (mock events -> props), node:test
+├── index.ts            # Barrel: contracts + adapters + (later) vendored re-exports
+└── vendors/
+    └── beautifului/    # Vendored BeautifulUI components (added during migration)
+```
+
+**Rule:** BeautifulUI / upstream prop types must **never** be imported outside
+`src/agent-ui/`. Consumers depend on `contracts.ts` only, so the vendored
+implementation can be swapped later without touching call sites.
+
+### 2. Adapter contracts
+
+Internal, transport-agnostic types live in `contracts.ts`:
+
+- `AgentStreamEvent` — normalized form of the WebSocket frames handled in
+  `chat.js` (`run_started`, `run_content`, `tool_call_started`, …). Unknown
+  frame `type`s degrade to `kind: 'unknown'` with `rawType` preserved instead
+  of throwing, so new upstream events never break the UI.
+- `ToolCallChipModel` — tool-call chip view model.
+- `ApprovalPromptModel` — approval card view model, mapped from the
+  `/api/approvals/pending` REST payload.
+
+Mappers (`adapter.ts`): `mapChatEventToUi(frame)` and
+`mapApprovalToCardProps(item)`. Both are **pure** and unit tested.
+
+### 3. Vendoring & pin policy
+
+| Mechanism | Purpose |
+|-----------|---------|
+| [`BEAUTIFULUI_UPSTREAM.md`](./BEAUTIFULUI_UPSTREAM.md) | Record git SHA, date, registry base URL for every vendored component |
+| shadcn registry URLs | Per-component install, pinned in the upstream doc |
+| **No** `dependencies.beautiful-ui` in `package.json` | Avoid a phantom npm package |
+
+**Upgrade rule:** bump upstream **only** via a PR that updates
+`BEAUTIFULUI_UPSTREAM.md` and passes the frontend CI gate (issue #295). Icons
+stay on `lucide-react`; do not vendor paid Central icons.
+
+### 4. Feature flag (default **off**)
+
+Integration is gated so the existing vanilla-JS chat/approvals plugins remain
+the fallback until migration milestones (#296, #297) complete.
+
+- **Flag:** `AIUI_BEAUTIFULUI` (build-time env / dashboard config JSON).
+- **Default:** off — vanilla JS renders; the adapter is imported but not mounted.
+- **On:** React islands mount using `src/agent-ui` contracts.
+- **Fallback:** if a vendored component fails to load, the flag is treated as
+  off and the vanilla path renders. No user-facing regression when off.
+
+### 5. Design tokens
+
+Scope agent-UI primitives under an `.aiui-agent-ui { … }` CSS layer (or extend
+the existing shadcn presets in `themes.py`) so vendored component tokens cannot
+collide with the global dashboard theme.
+
+### 6. Deprecation / upstream abandonment
+
+Vendored code stays MIT-licensed in-tree. Because consumers depend only on the
+`contracts.ts` view models, a future first-party implementation can satisfy the
+same contracts and replace the vendored components with no call-site churn.
+
+## Consequences
+
+- One place (`src/agent-ui/`) owns the upstream coupling.
+- Adapters are testable without a browser or the transport layer.
+- The default-off flag keeps the migration reversible at every step.

docs/frontend/beautifului.md

@@ -0,0 +1,107 @@
+# BeautifulUI Upgrade Playbook
+
+How PraisonAIUI vendors [BeautifulUI](https://www.beautifului.dev/) React primitives so
+upgrades are **repeatable** and licence obligations are **explicit**.
+
+!!! info "Related planning"
+    Epic [#292](https://github.com/MervinPraison/PraisonAIUI/issues/292) (integration
+    strategy) and the adapter/pin policy in
+    [#294](https://github.com/MervinPraison/PraisonAIUI/issues/294).
+
+## 1. What BeautifulUI is
+
+BeautifulUI (MIT, © Shane Levine / Turbo) is a library of React primitives aimed at
+**AI-native interfaces** — thinking traces, streaming answers with inline sources,
+human-in-the-loop approval cards, tool chips, task rows, context chunks, and a reference
+chat harness.
+
+**It is a shadcn registry + copy-paste library — not an npm package.** There is no
+published `beautiful-ui` package. You install components by resolving a registry URL, and
+the source is copied into your tree (like any other shadcn/ui primitive).
+
+- Website & registry: <https://www.beautifului.dev/>
+- Upstream source: <https://github.com/slev12397/beautiful-ui>
+
+Upstream stack (Next.js 15 · React 19 · Tailwind CSS v4 · TypeScript) is closely aligned
+with PraisonAIUI's `src/frontend` (Vite · React 19 · Tailwind v4 · shadcn/Radix), which is
+why copy-paste vendoring works without a framework shim.
+
+## 2. One-time foundation setup
+
+PraisonAIUI already carries the shadcn/ui foundation that BeautifulUI primitives depend on:
+
+- **shadcn config** — `src/frontend/components.json` (`style: new-york`,
+  `baseColor: neutral`, `iconLibrary: lucide`, `cssVariables: true`). Its `registries`
+  map is where pinned BeautifulUI registry URLs are added (see §3).
+- **Theme tokens** — `src/praisonaiui/themes.py` generates the shadcn CSS variables
+  (`--background`, `--foreground`, `--primary`, `--radius`, …) at build time for all 22
+  official presets, offline. BeautifulUI's foundation CSS (upstream `app/globals.css`)
+  must only contribute **new** tokens/utilities; it must **not** redefine variables that
+  `themes.py` already owns, or theme switching and dark mode break.
+
+**Rule:** when merging upstream `app/globals.css`, diff it against the variables emitted by
+`themes.py` and keep only the additive slices (new keyframes, component-scoped utilities).
+Record what was merged in the pin doc (§3).
+
+## 3. Adding or updating a primitive
+
+1. **Install with a pinned registry URL** from `src/frontend/`:
+   ```bash
+   npx shadcn add https://www.beautifului.dev/r/<component>.json
+   ```
+   The registry resolves dependencies and CSS slices. Commit the resulting
+   `package-lock.json` change in the same PR.
+2. **Re-export through the adapter** — add the component to
+   `src/frontend/src/components/index.ts` (`@praisonaiui/react`). Consumers never import
+   the raw vendored path (see §4).
+3. **Update the pin record** — create/update `docs/frontend/BEAUTIFULUI_UPSTREAM.md` with:
+   the upstream **git SHA**, the **date**, the **registry base URL**, and the **component
+   list** vendored so far. This file is the single source of truth for "what version are
+   we on". (It is created the first time a real primitive is vendored — do not add it
+   empty.)
+4. **Rebuild & sync the bundle** — the committed frontend bundle must be regenerated:
+   ```bash
+   cd src/frontend && npm run build
+   # then sync dist/{index.html,assets/,icon.svg} → src/praisonaiui/templates/frontend/
+   ```
+   (See `AGENTS.md` → "Frontend Build".)
+5. **Run frontend CI** — `.github/workflows/ci.yml` (ruff + pytest) must pass, plus the
+   frontend build step.
+
+## 4. Adapter boundary
+
+Consumers import from **`@praisonaiui/react` only** — never from raw vendored paths such as
+`@/components/ui/...` or any upstream module.
+
+```tsx
+// ✅ stable PraisonAIUI contract
+import { Button, ThemeToggle } from '@praisonaiui/react'
+
+// ❌ leaks upstream/shadcn paths across the codebase
+import { Button } from '@/components/ui/button'
+```
+
+This keeps the upstream surface behind one file (`components/index.ts`), so a BeautifulUI
+bump changes vendored source but not consumer imports.
+
+## 5. Rollback
+
+- BeautifulUI-backed views mount behind a **feature flag**; the **vanilla dashboard views**
+  (`src/praisonaiui/templates/frontend/plugins/*`) remain the fallback and are kept working.
+- To roll back a bad bump: revert the vendoring PR (source + `BEAUTIFULUI_UPSTREAM.md` +
+  rebuilt bundle move together in one commit), and disable the flag. No consumer import
+  changes are needed because everything routes through the adapter (§4).
+
+## 6. Licence
+
+BeautifulUI is **MIT, © Shane Levine**. The full licence text is retained in
+[`THIRD_PARTY_NOTICES.md`](https://github.com/MervinPraison/PraisonAIUI/blob/main/THIRD_PARTY_NOTICES.md)
+at the repository root. Any PR that vendors or bumps BeautifulUI source must keep that
+notice present and current.
+
+## 7. Commercial icons — do not vendor
+
+Do **not** use `@central-icons-react` without a licence — it is commercial. PraisonAIUI
+standardises on **`lucide-react`** (`iconLibrary: lucide` in `components.json`). If an
+upstream BeautifulUI primitive imports commercial icons, swap them for lucide equivalents
+during vendoring.

mkdocs.yml

@@ -95,8 +95,12 @@ nav:
     - Templates & Layouts: concepts/templates.md
     - Slots & Components: concepts/slots.md
     - Providers: concepts/providers.md
+  - Frontend:
+    - BeautifulUI Adapter: frontend/beautifului-adapter-architecture.md
+    - BeautifulUI Upstream Pin: frontend/BEAUTIFULUI_UPSTREAM.md
   - Features:
     - Dashboard: features/dashboard.md
+    - Replay: features/replay.md
     - Gateway Chat: features/gateway-chat.md
     - Attachments: features/attachments.md
     - Theme System: features/theme-system.md
@@ -129,12 +133,15 @@ nav:
     - Feature Inventory: features/feature-inventory.md
     - Gap Analysis: features/gap-analysis.md
     - Integration Analysis: features/integration-analysis.md
+    - BeautifulUI Integration: features/beautifului-integration.md
     - Standardization: features/standardization-verification.md
     - Comparison (OpenClaw): features/comparison-openclaw.md
     - What Makes It Different: features/differentiation.md
     - How to Add a Feature: features/how-to-add-a-feature.md
     - Message Elements: features/message-elements.md
     - Steps: features/steps.md
+  - Frontend:
+    - BeautifulUI Playbook: frontend/beautifului.md
   - API Reference:
     - Python CLI: api/cli.md
     - Python API: api/python.md

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aiui"
-version = "0.3.146"
+version = "0.3.151"
 description = "YAML-driven website generator - CLI and compiler"
 readme = "README.md"
 license = {text = "MIT"}

src/frontend/README.md

@@ -1,6 +1,27 @@
-# React + TypeScript + Vite
+# PraisonAIUI Frontend (React + TypeScript + Vite)
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+The BeautifulUI dashboard source. Built with React 19 + Vite 7 + Tailwind v4.
+
+## Build & CI
+
+- **Node.js:** 22 (matches the `frontend` job in `.github/workflows/ci.yml`)
+- **Lockfile:** `src/frontend/package-lock.json` — install with `npm ci`
+
+```bash
+cd src/frontend
+npm ci
+npm run build       # SPA build → dist/ (dashboard ship path)
+npm run build:lib   # library build for the @praisonaiui/react package
+npm run lint        # eslint
+```
+
+`npm run build` output in `dist/` is synced to `src/praisonaiui/templates/frontend/`
+(the committed bundle served by `aiui build`). The CI `frontend` job runs
+`npm ci && npm run build` on PRs to `main` and fails on TypeScript/Vite errors.
+
+## Vite template notes
+
+This project uses a minimal setup to get React working in Vite with HMR and some ESLint rules.
 
 Currently, two official plugins are available:
 

src/frontend/package-lock.json

@@ -82,20 +82,6 @@
         }
       }
     },
-    "node_modules/@a2ui/markdown-it": {
-      "version": "0.0.4",
-      "resolved": "https://registry.npmjs.org/@a2ui/markdown-it/-/markdown-it-0.0.4.tgz",
-      "integrity": "sha512-uaYNywdiHDH4i//pHpyckFnApvOshiUNT2Xl8awceNjL1XAX/gqtki9GRUJQ26RE7id2+aPNgOy1W6mXNBxriQ==",
-      "dev": true,
-      "license": "Apache-2.0",
-      "dependencies": {
-        "dompurify": "^3.3.1",
-        "markdown-it": "^14.1.0"
-      },
-      "peerDependencies": {
-        "@a2ui/web_core": "^0.9.2"
-      }
-    },
     "node_modules/@a2ui/react": {
       "version": "0.10.0",
       "resolved": "https://registry.npmjs.org/@a2ui/react/-/react-0.10.0.tgz",
@@ -129,16 +115,16 @@
       }
     },
     "node_modules/@a2ui/web_core": {
-      "version": "0.10.0",
-      "resolved": "https://registry.npmjs.org/@a2ui/web_core/-/web_core-0.10.0.tgz",
-      "integrity": "sha512-pSieKxaB6aZWBL2LjZfKo4/1v4xMWylczpzte1ehuGH0kfNGf/iTd73PKsIKYx3b0FNWTbD8gAloOM4JCVqUig==",
+      "version": "0.10.2",
+      "resolved": "https://registry.npmjs.org/@a2ui/web_core/-/web_core-0.10.2.tgz",
+      "integrity": "sha512-IfS4K7baTL9P9AzUOzKRWzL9A9/+Z7TCgMY2GPwsZ0H7LgY/9/uJnlbReNhpHsAfN12KZtW9iERWkw5HOf71GA==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
-        "@preact/signals-core": "^1.13.0",
-        "date-fns": "^4.1.0",
+        "@preact/signals-core": "^1.14.2",
+        "date-fns": "^4.4.0",
         "zod": "^3.25.76",
-        "zod-to-json-schema": "^3.25.1"
+        "zod-to-json-schema": "^3.25.2"
       }
     },
     "node_modules/@a2ui/web_core/node_modules/zod": {
@@ -5502,9 +5488,9 @@
       }
     },
     "node_modules/date-fns": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-4.1.0.tgz",
-      "integrity": "sha512-Ukq0owbQXxa/U3EGtsdVBkR1w7KOQ5gIBqdH2hkvknzZPYvBxb/aa6E8L7tmjFtkwZBu3UXBbjIgPo/Ez4xaNg==",
+      "version": "4.4.0",
+      "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-4.4.0.tgz",
+      "integrity": "sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==",
       "license": "MIT",
       "funding": {
         "type": "github",
@@ -9747,6 +9733,84 @@
         "type": "github",
         "url": "https://github.com/sponsors/wooorm"
       }
+    },
+    "node_modules/@a2ui/react/node_modules/@a2ui/markdown-it": {
+      "version": "0.0.4",
+      "resolved": "https://registry.npmjs.org/@a2ui/markdown-it/-/markdown-it-0.0.4.tgz",
+      "integrity": "sha512-uaYNywdiHDH4i//pHpyckFnApvOshiUNT2Xl8awceNjL1XAX/gqtki9GRUJQ26RE7id2+aPNgOy1W6mXNBxriQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "dompurify": "^3.3.1",
+        "markdown-it": "^14.1.0"
+      },
+      "peerDependencies": {
+        "@a2ui/web_core": "^0.9.2"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": {
+      "version": "1.8.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.1.0",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": {
+      "version": "1.8.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
+      "version": "1.1.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": {
+      "version": "1.1.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "^1.7.1",
+        "@emnapi/runtime": "^1.7.1",
+        "@tybys/wasm-util": "^0.10.1"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/Brooooooklyn"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": {
+      "version": "0.10.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": {
+      "version": "2.8.1",
+      "dev": true,
+      "inBundle": true,
+      "license": "0BSD",
+      "optional": true
     }
   }
 }

src/frontend/package.json

@@ -29,7 +29,8 @@
     "build": "tsc -b && vite build",
     "build:lib": "tsc -b && vite build --mode lib",
     "lint": "eslint .",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "node --experimental-strip-types --test \"src/agent-ui/**/*.test.ts\""
   },
   "keywords": [
     "react",

src/frontend/src/agent-ui/adapter.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Unit tests for the Agent-UI adapter (mock events -> stable contracts).
+ *
+ * Dependency-free: uses the Node built-in test runner so it needs no extra
+ * toolchain. Run with `npm test` (from src/frontend), which invokes the Node
+ * test runner with `--experimental-strip-types` so the TypeScript types are
+ * stripped on Node 22+. The frontend CI gate (see issue #295) wires this in.
+ */
+
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { mapApprovalToCardProps, mapChatEventToUi } from './adapter.ts'
+
+test('mapChatEventToUi normalizes a streaming token frame', () => {
+    const event = mapChatEventToUi({
+        type: 'run_content',
+        token: 'Hello',
+        agent_name: 'Researcher',
+        session_id: 's1',
+        run_id: 'r1',
+    })
+    assert.equal(event.kind, 'run-token')
+    assert.equal(event.text, 'Hello')
+    assert.equal(event.agentName, 'Researcher')
+    assert.equal(event.sessionId, 's1')
+    assert.equal(event.runId, 'r1')
+})
+
+test('mapChatEventToUi maps a started tool call to a running chip', () => {
+    const event = mapChatEventToUi({
+        type: 'tool_call_started',
+        name: 'search',
+        description: '🔎 Searching the web',
+        icon: '🔎',
+        step_number: 2,
+        tool_call_id: 'tc-1',
+    })
+    assert.equal(event.kind, 'tool-call')
+    assert.deepEqual(event.toolCall, {
+        id: 'tc-1',
+        label: '🔎 Searching the web',
+        icon: '🔎',
+        stepNumber: 2,
+        status: 'running',
+        error: undefined,
+    })
+})
+
+test('mapChatEventToUi marks completed tool calls as done', () => {
+    const event = mapChatEventToUi({ type: 'tool_call_completed', name: 'search' })
+    assert.equal(event.toolCall?.status, 'done')
+    // Falls back to the tool name for id and label when unspecified.
+    assert.equal(event.toolCall?.id, 'search')
+    assert.equal(event.toolCall?.label, 'search')
+})
+
+test('mapChatEventToUi treats team_* frames the same as their solo variant', () => {
+    assert.equal(mapChatEventToUi({ type: 'team_run_content', token: 'x' }).kind, 'run-token')
+    assert.equal(mapChatEventToUi({ type: 'team_run_error', error: 'boom' }).kind, 'run-error')
+})
+
+test('mapChatEventToUi preserves unknown frame types without throwing', () => {
+    const event = mapChatEventToUi({ type: 'future_event', foo: 'bar' })
+    assert.equal(event.kind, 'unknown')
+    assert.equal(event.rawType, 'future_event')
+})
+
+test('mapChatEventToUi defaults run errors to a readable message', () => {
+    const event = mapChatEventToUi({ type: 'run_error' })
+    assert.equal(event.kind, 'run-error')
+    assert.equal(event.error, 'Unknown error')
+})
+
+test('mapApprovalToCardProps maps a pending approval item', () => {
+    const card = mapApprovalToCardProps({
+        id: 'a-1',
+        tool_name: 'delete_file',
+        agent_name: 'Ops',
+        risk_level: 'high',
+        risk_icon: '🔥',
+        description: 'Deletes a file',
+        arguments: { path: '/tmp/x' },
+        // Approvals API emits epoch seconds (time.time()), not an ISO string.
+        created_at: 1758585600,
+    })
+    assert.equal(card.id, 'a-1')
+    assert.equal(card.toolName, 'delete_file')
+    assert.equal(card.agentName, 'Ops')
+    assert.equal(card.riskLevel, 'high')
+    assert.equal(card.riskIcon, '🔥')
+    assert.equal(card.argumentsJson, '{\n  "path": "/tmp/x"\n}')
+    // Epoch seconds are normalized to an ISO-8601 string for display.
+    assert.equal(card.createdAt, '2025-09-23T00:00:00.000Z')
+})
+
+test('mapApprovalToCardProps falls back for missing/invalid fields', () => {
+    const card = mapApprovalToCardProps({ id: 'a-2', risk_level: 'nonsense' })
+    assert.equal(card.toolName, 'unknown')
+    assert.equal(card.agentName, 'Unknown')
+    assert.equal(card.riskLevel, 'medium')
+    assert.equal(card.riskIcon, '⚠️')
+    assert.equal(card.argumentsJson, '{}')
+})

src/frontend/src/agent-ui/adapter.ts

@@ -0,0 +1,177 @@
+/**
+ * PraisonAIUI Agent-UI adapter
+ *
+ * Pure mapping functions from wire payloads to stable PraisonAIUI contracts.
+ * This is the single boundary between transport shapes (WebSocket frames from
+ * chat.js, REST payloads from /api/approvals/*) and the UI layer. Vendored
+ * BeautifulUI components are rendered from these contracts elsewhere in
+ * `src/agent-ui/`; consumers never import upstream prop types directly.
+ *
+ * Functions are intentionally side-effect free so they can be unit tested
+ * with mock events (see adapter.test.ts).
+ */
+
+import type {
+    AgentStreamEvent,
+    ApprovalPromptModel,
+    ApprovalRiskLevel,
+    ToolCallChipModel,
+} from './contracts'
+
+/** Raw WebSocket frame as parsed in chat.js (`JSON.parse(event.data)`). */
+export type RawChatFrame = Record<string, unknown>
+
+/** Raw approval item as returned by `/api/approvals/pending`. */
+export type RawApprovalItem = Record<string, unknown>
+
+const VALID_RISK_LEVELS: readonly ApprovalRiskLevel[] = [
+    'low',
+    'medium',
+    'high',
+    'critical',
+]
+
+function asString(value: unknown): string | undefined {
+    return typeof value === 'string' ? value : undefined
+}
+
+function asNumber(value: unknown): number | undefined {
+    return typeof value === 'number' ? value : undefined
+}
+
+/**
+ * Normalize a `created_at` value to an ISO-8601 string. The approvals API
+ * emits epoch seconds (`time.time()`), while some payloads already carry an
+ * ISO string — accept both, drop anything else.
+ */
+function asTimestamp(value: unknown): string | undefined {
+    if (typeof value === 'string') return value
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return new Date(value * 1000).toISOString()
+    }
+    return undefined
+}
+
+/** Map a raw tool-call frame to a stable chip view model. */
+function mapToolCall(
+    frame: RawChatFrame,
+    status: ToolCallChipModel['status'],
+): ToolCallChipModel {
+    const name = asString(frame.name) ?? 'tool'
+    return {
+        id: asString(frame.tool_call_id) ?? name,
+        label: asString(frame.description) ?? name,
+        icon: asString(frame.icon),
+        stepNumber: asNumber(frame.step_number),
+        status,
+        error: asString(frame.error),
+    }
+}
+
+/**
+ * Map a raw WebSocket chat frame to a normalized {@link AgentStreamEvent}.
+ *
+ * Unknown frame types are preserved as `kind: 'unknown'` with `rawType` set,
+ * so new upstream event types degrade gracefully instead of throwing.
+ */
+export function mapChatEventToUi(frame: RawChatFrame): AgentStreamEvent {
+    const rawType = asString(frame.type)
+    const sessionId = asString(frame.session_id)
+    const runId = asString(frame.run_id)
+    const agentName = asString(frame.agent_name)
+
+    switch (rawType) {
+        case 'run_started':
+            return { kind: 'run-started', sessionId, runId, agentName }
+        case 'run_content':
+        case 'team_run_content':
+            return {
+                kind: 'run-token',
+                sessionId,
+                runId,
+                agentName,
+                text: asString(frame.token),
+            }
+        case 'run_completed':
+        case 'team_run_completed':
+            return {
+                kind: 'run-completed',
+                sessionId,
+                runId,
+                agentName,
+                text: asString(frame.content),
+            }
+        case 'run_error':
+        case 'team_run_error':
+            return {
+                kind: 'run-error',
+                sessionId,
+                runId,
+                agentName,
+                error: asString(frame.error) ?? 'Unknown error',
+            }
+        case 'tool_call_started':
+        case 'team_tool_call_started':
+            return {
+                kind: 'tool-call',
+                sessionId,
+                runId,
+                agentName,
+                toolCall: mapToolCall(frame, 'running'),
+            }
+        case 'tool_call_completed':
+        case 'team_tool_call_completed':
+            return {
+                kind: 'tool-call',
+                sessionId,
+                runId,
+                agentName,
+                toolCall: mapToolCall(frame, 'done'),
+            }
+        case 'reasoning_step':
+        case 'team_reasoning_step':
+            return {
+                kind: 'reasoning-step',
+                sessionId,
+                runId,
+                agentName,
+                text: asString(frame.step),
+            }
+        default:
+            return { kind: 'unknown', sessionId, runId, agentName, rawType }
+    }
+}
+
+function normalizeRisk(value: unknown): ApprovalRiskLevel {
+    return VALID_RISK_LEVELS.includes(value as ApprovalRiskLevel)
+        ? (value as ApprovalRiskLevel)
+        : 'medium'
+}
+
+/**
+ * Map a raw approval item from `/api/approvals/pending` to a stable
+ * {@link ApprovalPromptModel}. Arguments are pretty-printed for display and
+ * an unknown/missing risk level falls back to `medium`.
+ */
+export function mapApprovalToCardProps(
+    item: RawApprovalItem,
+): ApprovalPromptModel {
+    let argumentsJson = '{}'
+    try {
+        argumentsJson = JSON.stringify(item.arguments ?? {}, null, 2)
+    } catch {
+        // Circular or non-serializable args — degrade to empty object.
+        argumentsJson = '{}'
+    }
+
+    return {
+        id: asString(item.id) ?? '',
+        toolName: asString(item.tool_name) ?? 'unknown',
+        agentName: asString(item.agent_name) ?? 'Unknown',
+        riskLevel: normalizeRisk(item.risk_level),
+        riskIcon: asString(item.risk_icon) ?? '⚠️',
+        description: asString(item.description),
+        argumentsJson,
+        createdAt: asTimestamp(item.created_at),
+    }
+}

src/frontend/src/agent-ui/contracts.ts

@@ -0,0 +1,69 @@
+/**
+ * PraisonAIUI Agent-UI contracts
+ *
+ * Stable, framework-agnostic view models owned by PraisonAIUI. These are the
+ * ONLY types that non-adapter code (chat views, dashboards, tests) should
+ * depend on. BeautifulUI / vendored component prop types must never leak
+ * outside `src/agent-ui/` — the adapter maps to these contracts instead so
+ * the upstream implementation can be swapped without touching consumers.
+ *
+ * See docs/frontend/beautifului-adapter-architecture.md.
+ */
+
+/** Discriminant for a normalized agent stream event. */
+export type AgentStreamEventKind =
+    | 'run-started'
+    | 'run-token'
+    | 'run-completed'
+    | 'run-error'
+    | 'tool-call'
+    | 'reasoning-step'
+    | 'unknown'
+
+/**
+ * Normalized agent stream event — the stable shape UI code consumes,
+ * decoupled from the raw WebSocket frame `type` strings handled in chat.js.
+ */
+export interface AgentStreamEvent {
+    kind: AgentStreamEventKind
+    /** Owning session, when the frame carried one. */
+    sessionId?: string
+    /** Run identifier, when the frame carried one. */
+    runId?: string
+    /** Human-facing agent name, when present. */
+    agentName?: string
+    /** Streaming token or final content, depending on `kind`. */
+    text?: string
+    /** Populated for `kind === 'tool-call'`. */
+    toolCall?: ToolCallChipModel
+    /** Populated for `kind === 'run-error'`. */
+    error?: string
+    /** Raw frame `type` for events we do not yet normalize (`kind === 'unknown'`). */
+    rawType?: string
+}
+
+/** View model for a tool-call chip, independent of any component library. */
+export interface ToolCallChipModel {
+    id: string
+    label: string
+    icon?: string
+    stepNumber?: number
+    status: 'running' | 'done' | 'error'
+    error?: string
+}
+
+/** Risk levels surfaced by the approvals REST API (`/api/approvals/*`). */
+export type ApprovalRiskLevel = 'low' | 'medium' | 'high' | 'critical'
+
+/** View model for an approval prompt/card, independent of any component library. */
+export interface ApprovalPromptModel {
+    id: string
+    toolName: string
+    agentName: string
+    riskLevel: ApprovalRiskLevel
+    riskIcon: string
+    description?: string
+    /** Pretty-printed tool arguments, ready for display. */
+    argumentsJson: string
+    createdAt?: string
+}

src/frontend/src/agent-ui/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Agent-UI boundary barrel.
+ *
+ * Consumers import PraisonAIUI's stable agent-UI contracts and adapters from
+ * here. Vendored BeautifulUI components live under `src/agent-ui/vendors/` and
+ * are re-exported from this folder only — no upstream prop types should be
+ * imported outside `src/agent-ui/`.
+ */
+
+export type {
+    AgentStreamEvent,
+    AgentStreamEventKind,
+    ApprovalPromptModel,
+    ApprovalRiskLevel,
+    ToolCallChipModel,
+} from './contracts'
+
+export type { RawApprovalItem, RawChatFrame } from './adapter'
+export { mapApprovalToCardProps, mapChatEventToUi } from './adapter'

src/frontend/src/chat/ActionButtons.tsx

@@ -38,7 +38,7 @@ interface ActionButtonsProps {
  */
 export function ActionButtons({ actions, messageId, sessionId }: ActionButtonsProps) {
     const [pendingActions, setPendingActions] = useState<Set<string>>(new Set())
-    const [hiddenActions, setHiddenActions] = useState<Set<string>>(new Set())
+    const [hiddenActions] = useState<Set<string>>(new Set())
 
     const handleActionClick = useCallback(async (action: ActionButton) => {
         if (pendingActions.has(action.id) || hiddenActions.has(action.id)) {

src/frontend/src/chat/AskActionPrompt.tsx

@@ -73,7 +73,7 @@ export function AskActionPrompt({
 
             {/* Action buttons */}
             <div className="space-y-3">
-                {actions.map((action, index) => (
+                {actions.map((action) => (
                     <button
                         key={action.name}
                         type="button"

src/frontend/src/chat/ChatSettingsPanel.tsx

@@ -15,7 +15,7 @@ import { Textarea } from '../components/ui/textarea';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../components/ui/select';
 import { Slider } from '../components/ui/slider';
 import { Switch } from '../components/ui/switch';
-import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '../components/ui/card';
+import { Card, CardContent } from '../components/ui/card';
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription } from '../components/ui/sheet';
 
 interface SettingsWidget {
@@ -74,7 +74,7 @@ const WidgetRenderer: React.FC<{
               id={name}
               placeholder={placeholder}
               value={value || ''}
-              onChange={(e) => onChange(e.target.value)}
+              onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => onChange(e.target.value)}
               maxLength={widget.maxLength}
               rows={4}
             />

src/frontend/src/chat/CustomElementHost.tsx

@@ -20,43 +20,16 @@ interface CustomElementProps {
   onError?: (error: Error) => void;
 }
 
-interface CustomComponentModule {
-  default: React.ComponentType<any>;
-}
-
 // Registry of loaded components (cache)
 const componentCache = new Map<string, Promise<React.ComponentType<any>>>();
 
-// List of available custom components (in practice, this would be populated from backend)
-const availableComponents = new Set([
-  'ExampleWidget',
-  'UserCard',
-  'DataChart', 
-  'FormBuilder',
-  'CodeEditor',
-  'ImageGallery',
-  'ChatEmbed'
-]);
-
-// Static imports for build-tool compatibility
-const ExampleWidget = React.lazy(() => import('../components/custom/ExampleWidget'));
-const UserCard = React.lazy(() => import('../components/custom/UserCard'));
-const DataChart = React.lazy(() => import('../components/custom/DataChart'));
-const FormBuilder = React.lazy(() => import('../components/custom/FormBuilder'));
-const CodeEditor = React.lazy(() => import('../components/custom/CodeEditor'));
-const ImageGallery = React.lazy(() => import('../components/custom/ImageGallery'));
-const ChatEmbed = React.lazy(() => import('../components/custom/ChatEmbed'));
-
-// Static mapping of component names to imports
-const componentMap: Record<string, React.ComponentType<any>> = {
-  ExampleWidget,
-  UserCard,
-  DataChart,
-  FormBuilder,
-  CodeEditor,
-  ImageGallery,
-  ChatEmbed,
-};
+// Custom components available to <CustomElementHost name="..." />. The example
+// widgets this once listed (ExampleWidget, UserCard, ...) were never added, and
+// importing them broke the build. Register real components here as they land:
+//   const MyWidget = React.lazy(() => import('../components/custom/MyWidget'));
+//   componentMap.MyWidget = MyWidget;
+const componentMap: Record<string, React.ComponentType<any>> = {};
+const availableComponents = new Set(Object.keys(componentMap));
 
 /**
  * Load a custom component with static mapping for build-tool compatibility

src/frontend/src/chat/TaskSidebar.tsx

@@ -4,7 +4,6 @@
  * Shows live-updating task lists with states, progress bars, and click-to-jump functionality.
  */
 
-import React from 'react'
 import { ChevronRight, ChevronDown, CheckCircle, Clock, XCircle, Circle, ExternalLink } from 'lucide-react'
 import { useTaskState, setTasksCollapsed, type Task, type TaskList, type TaskStatus } from '../state/tasks'
 import { cn } from '../lib/utils'

src/frontend/src/components/ui/alert.tsx

@@ -0,0 +1,44 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const alertVariants = cva(
+  "relative w-full rounded-lg border px-4 py-3 text-sm [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground [&>svg~*]:pl-7",
+  {
+    variants: {
+      variant: {
+        default: "bg-background text-foreground",
+        destructive:
+          "border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+const Alert = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
+>(({ className, variant, ...props }, ref) => (
+  <div ref={ref} role="alert" className={cn(alertVariants({ variant }), className)} {...props} />
+))
+Alert.displayName = "Alert"
+
+const AlertTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLHeadingElement>>(
+  ({ className, ...props }, ref) => (
+    <h5 ref={ref} className={cn("mb-1 font-medium leading-none tracking-tight", className)} {...props} />
+  )
+)
+AlertTitle.displayName = "AlertTitle"
+
+const AlertDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn("text-sm [&_p]:leading-relaxed", className)} {...props} />
+  )
+)
+AlertDescription.displayName = "AlertDescription"
+
+export { Alert, AlertTitle, AlertDescription }

src/frontend/src/components/ui/textarea.tsx

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+const Textarea = React.forwardRef<HTMLTextAreaElement, React.ComponentProps<"textarea">>(
+  ({ className, ...props }, ref) => (
+    <textarea
+      className={cn(
+        "flex min-h-[60px] w-full rounded-md border border-input bg-transparent px-3 py-2 text-base shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        className
+      )}
+      ref={ref}
+      {...props}
+    />
+  )
+)
+Textarea.displayName = "Textarea"
+
+export { Textarea }

src/frontend/src/hooks/useMicStream.ts

@@ -183,7 +183,7 @@ export function useMicStream(options: UseMicStreamOptions = {}): UseMicStreamRet
       onConnectionChangeRef.current?.(false);
     };
     
-    ws.onerror = (error) => {
+    ws.onerror = () => {
       onErrorRef.current?.(new Error('WebSocket error'));
       setConnected(false);
       onConnectionChangeRef.current?.(false);

src/frontend/src/hooks/useWindowMessage.ts

@@ -5,8 +5,33 @@
  * incoming messages from parent.
  */
 
-import { useEffect, useCallback, useRef } from 'react';
-import { useSSE } from './useSSE';
+import { useEffect, useCallback, useRef, useState } from 'react';
+
+interface EventSourceOptions {
+  enabled?: boolean;
+  onMessage?: (event: MessageEvent) => void;
+  onOpen?: () => void;
+  onError?: () => void;
+}
+
+/**
+ * Minimal EventSource subscription. (useSSE in this package is the chat
+ * streaming store, not a generic SSE hook, so it cannot open this stream.)
+ */
+function useEventSource(url: string, { enabled = true, onMessage, onOpen, onError }: EventSourceOptions) {
+  const [connected, setConnected] = useState(false);
+  const handlers = useRef({ onMessage, onOpen, onError });
+  handlers.current = { onMessage, onOpen, onError };
+  useEffect(() => {
+    if (!enabled || typeof EventSource === 'undefined') return;
+    const source = new EventSource(url);
+    source.onopen = () => { setConnected(true); handlers.current.onOpen?.(); };
+    source.onmessage = (event) => handlers.current.onMessage?.(event);
+    source.onerror = () => { setConnected(false); handlers.current.onError?.(); };
+    return () => { source.close(); setConnected(false); };
+  }, [url, enabled]);
+  return { connected };
+}
 
 export interface WindowMessageData {
   type: string;
@@ -85,7 +110,7 @@ export function useWindowMessage(options: UseWindowMessageOptions = {}): UseWind
   const isIframe = window !== window.parent;
   
   // SSE connection for outbound messages
-  const { connected } = useSSE('/sse/window-message', {
+  const { connected } = useEventSource('/sse/window-message', {
     enabled: enabled && isIframe,
     onMessage: (event) => {
       try {

src/frontend/src/modals/AddMCPServerModal.tsx

@@ -7,9 +7,7 @@ import React, { useState } from 'react';
 import { Button } from '../components/ui/button';
 import { Input } from '../components/ui/input';
 import { Label } from '../components/ui/label';
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../components/ui/select';
 import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogFooter } from '../components/ui/dialog';
-import { Separator } from '../components/ui/separator';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '../components/ui/tabs';
 
 interface AddMCPServerModalProps {

src/frontend/src/pages/SharedThread.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from 'react';
-import { useParams } from 'react-router-dom';
 import { Eye, AlertCircle } from 'lucide-react';
 import { ChatMessages } from '../chat/ChatMessages';
+import type { ChatMessage } from '../types';
 import { Button } from '../components/ui/button';
 
 interface SharedThreadData {
@@ -11,18 +11,13 @@ interface SharedThreadData {
     title: string;
     created_at: string;
   };
-  messages: Array<{
-    id: string;
-    role: string;
-    content: string;
-    timestamp: string;
-    toolCalls?: any[];
-  }>;
+  messages: ChatMessage[];
   read_only: boolean;
 }
 
 export function SharedThread() {
-  const { token } = useParams<{ token: string }>();
+  // Served at /shared/{token} (server.py); this app has no client-side router.
+  const token = decodeURIComponent(window.location.pathname.split('/shared/')[1]?.split('/')[0] ?? '');
   const [threadData, setThreadData] = useState<SharedThreadData | null>(null);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string>('');
@@ -128,10 +123,13 @@ export function SharedThread() {
         <div className="bg-white rounded-lg shadow-sm border border-gray-200 overflow-hidden">
           {threadData.messages.length > 0 ? (
             <div className="divide-y divide-gray-100">
-              <ChatMessages 
+              <ChatMessages
                 messages={threadData.messages}
                 sessionId={threadData.thread_id}
-                isSharedView={true}
+                currentResponse=""
+                thinkingSteps={[]}
+                toolCalls={[]}
+                isStreaming={false}
               />
             </div>
           ) : (

src/praisonaiui/__version__.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.3.146"
+__version__ = "0.3.151"

src/praisonaiui/features/__init__.py

@@ -80,6 +80,7 @@ def auto_register_defaults() -> None:
         (".tts", "TTSFeature"),
         (".usage", "UsageFeature"),
         (".realtime", "RealtimeFeature"),
+        (".replay", "ReplayFeature"),
         (".workflows", "WorkflowsFeature"),
         (".guardrails", "GuardrailsFeature"),
         (".eval", "EvalFeature"),

src/praisonaiui/features/_trace_jsonl.py

@@ -0,0 +1,517 @@
+"""Stdlib reader for PraisonAI context-trace JSONL files (Replay contract v1, section 1).
+
+One file per run at ``<traces dir>/<run_or_session_id>.jsonl``; one JSON object
+(``ContextEvent.to_dict()``) per line, in append order.  Readers must tolerate:
+
+* a partially written last line (it is skipped until it is complete);
+* unknown fields and unknown ``event_type`` values (passed through untouched);
+* schema 1.0 files (no ``run_id`` / ``parent_seq`` / ``node_id``).
+
+Shared by the ``replay`` feature (runs, events, SSE tail) and the ``tracing``
+feature (spans from start/end pairs).  No third-party imports.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+__all__ = [
+    "RUN_ID_RE",
+    "LIVE_WINDOW_S",
+    "traces_dir",
+    "is_valid_run_id",
+    "run_path",
+    "list_run_files",
+    "read_events",
+    "TailReader",
+    "EndTracker",
+    "find_graph",
+    "summarize_run",
+    "build_spans",
+]
+
+#: Allowed run ids: one path segment, no separators (path-traversal safe).
+RUN_ID_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+#: A run without an end marker counts as live while its file changed this recently.
+LIVE_WINDOW_S = 15 * 60
+
+#: start event type -> the end event type that closes it.
+START_END: Dict[str, str] = {
+    "session_start": "session_end",
+    "workflow_start": "workflow_end",
+    "task_start": "task_end",
+    "step_start": "step_end",
+    "agent_start": "agent_end",
+    "tool_call_start": "tool_call_end",
+    "llm_request": "llm_response",
+    "approval_requested": "approval_decided",
+}
+END_START: Dict[str, str] = {v: k for k, v in START_END.items()}
+
+_SPAN_KIND = {
+    "session_start": "session",
+    "workflow_start": "workflow",
+    "task_start": "task",
+    "step_start": "step",
+    "agent_start": "agent",
+    "tool_call_start": "tool",
+    "llm_request": "llm",
+    "approval_requested": "approval",
+}
+
+
+# ── Location ──────────────────────────────────────────────────────────
+
+
+def traces_dir() -> Path:
+    """Resolve the traces directory.
+
+    Precedence: ``$PRAISONAI_TRACES_DIR`` > ``$PRAISON_HOME/traces`` > ``~/.praison/traces``.
+    Never creates the directory (this module is read-only).
+    """
+    override = os.environ.get("PRAISONAI_TRACES_DIR")
+    if override:
+        return Path(override).expanduser()
+    home = os.environ.get("PRAISON_HOME")
+    base = Path(home).expanduser() if home else Path.home() / ".praison"
+    return base / "traces"
+
+
+def is_valid_run_id(run_id: Any) -> bool:
+    """True when *run_id* is a single safe path segment."""
+    return (
+        isinstance(run_id, str)
+        and 0 < len(run_id) <= 200
+        and run_id not in (".", "..")
+        and bool(RUN_ID_RE.match(run_id))
+    )
+
+
+def run_path(run_id: str, directory: Optional[Path] = None) -> Optional[Path]:
+    """Return the JSONL path for *run_id*, or ``None`` when the id is unsafe.
+
+    The resolved path is additionally checked to sit directly inside the
+    traces directory, so a symlinked or odd id can never escape it.
+    """
+    if not is_valid_run_id(run_id):
+        return None
+    base = directory or traces_dir()
+    candidate = base / f"{run_id}.jsonl"
+    try:
+        if candidate.resolve().parent != base.resolve():
+            return None
+    except OSError:
+        return None
+    return candidate
+
+
+def list_run_files(directory: Optional[Path] = None) -> List[Path]:
+    """All ``*.jsonl`` files with a valid id, newest (mtime) first."""
+    base = directory or traces_dir()
+    if not base.is_dir():
+        return []
+    items: List[Tuple[float, Path]] = []
+    for p in base.iterdir():
+        if p.suffix != ".jsonl" or not is_valid_run_id(p.stem):
+            continue
+        try:
+            st = p.stat()
+        except OSError:
+            continue
+        if p.is_file():
+            items.append((st.st_mtime, p))
+    items.sort(key=lambda it: (it[0], it[1].name), reverse=True)
+    return [p for _, p in items]
+
+
+# ── Reading ───────────────────────────────────────────────────────────
+
+
+def _parse_line(raw: bytes) -> Optional[Dict[str, Any]]:
+    raw = raw.strip()
+    if not raw:
+        return None
+    try:
+        obj = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError):
+        return None
+    return obj if isinstance(obj, dict) else None
+
+
+class TailReader:
+    """Incrementally read complete JSON lines from a growing file.
+
+    Keeps a byte offset; each :meth:`poll` returns only events whose line is
+    complete.  A trailing fragment without a newline is consumed only when it
+    already parses as a JSON object (a proper prefix of a JSON object never
+    does), so a half-written line is never surfaced.  If the file shrinks
+    (the writer truncates on restart), reading restarts from the top.
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self.offset = 0
+
+    def poll(self) -> List[Dict[str, Any]]:
+        try:
+            size = self.path.stat().st_size
+        except OSError:
+            return []
+        if size < self.offset:
+            self.offset = 0
+        if size == self.offset:
+            return []
+        try:
+            with open(self.path, "rb") as fh:
+                fh.seek(self.offset)
+                chunk = fh.read(size - self.offset)
+        except OSError:
+            return []
+        events: List[Dict[str, Any]] = []
+        consumed = 0
+        start = 0
+        while True:
+            nl = chunk.find(b"\n", start)
+            if nl < 0:
+                break
+            ev = _parse_line(chunk[start:nl])
+            if ev is not None:
+                events.append(ev)
+            start = nl + 1
+            consumed = start
+        tail = chunk[start:]
+        if tail.strip():
+            ev = _parse_line(tail)
+            if ev is not None:  # complete object, newline not written yet
+                events.append(ev)
+                consumed = len(chunk)
+        self.offset += consumed
+        return events
+
+
+_CACHE_LOCK = threading.Lock()
+_EVENT_CACHE: Dict[str, Tuple[Tuple[int, int], List[Dict[str, Any]]]] = {}
+_SUMMARY_CACHE: Dict[str, Tuple[Tuple[int, int, int], Dict[str, Any]]] = {}
+_EVENT_CACHE_MAX = 8
+_SUMMARY_CACHE_MAX = 512
+
+
+def _sig(path: Path) -> Optional[Tuple[int, int]]:
+    try:
+        st = path.stat()
+    except OSError:
+        return None
+    return (st.st_mtime_ns, st.st_size)
+
+
+def _seq(ev: Dict[str, Any], default: int = -1) -> int:
+    s = ev.get("sequence_num")
+    return s if isinstance(s, int) and not isinstance(s, bool) else default
+
+
+def read_events(path: Path, after_seq: Optional[int] = None) -> List[Dict[str, Any]]:
+    """All complete events in *path* (append order), optionally ``sequence_num > after_seq``."""
+    path = Path(path)
+    sig = _sig(path)
+    if sig is None:
+        return []
+    key = str(path)
+    with _CACHE_LOCK:
+        hit = _EVENT_CACHE.get(key)
+    if hit and hit[0] == sig:
+        events = hit[1]
+    else:
+        events = TailReader(path).poll()
+        with _CACHE_LOCK:
+            _EVENT_CACHE.pop(key, None)
+            _EVENT_CACHE[key] = (sig, events)
+            while len(_EVENT_CACHE) > _EVENT_CACHE_MAX:
+                _EVENT_CACHE.pop(next(iter(_EVENT_CACHE)))
+    if after_seq is None:
+        return list(events)
+    return [ev for ev in events if _seq(ev) > after_seq]
+
+
+# ── Interpretation ────────────────────────────────────────────────────
+
+
+class EndTracker:
+    """Decide when a run has finished, feeding events one at a time.
+
+    The outermost scope is the first ``session_start`` or, failing that, the
+    first top-level ``workflow_start``.  The run has ended once that scope's
+    end event arrives (``session_end`` always ends it).
+    """
+
+    def __init__(self) -> None:
+        self.outer: Optional[Tuple[str, int]] = None
+        self.first_workflow: Optional[int] = None
+        self.ended = False
+        self.status: Optional[str] = None
+        self.ended_at: Optional[float] = None
+
+    def feed(self, ev: Dict[str, Any]) -> None:
+        et = ev.get("event_type")
+        seq = _seq(ev)
+        if et == "session_start" and self.outer is None:
+            self.outer = ("session", seq)
+        elif et == "workflow_start":
+            if self.first_workflow is None:
+                self.first_workflow = seq
+            if self.outer is None and ev.get("parent_seq") is None:
+                self.outer = ("workflow", seq)
+        elif et == "workflow_end":
+            data = ev.get("data") or {}
+            ps = ev.get("parent_seq")
+            if ps is None or ps == self.first_workflow:
+                if isinstance(data, dict) and data.get("status"):
+                    self.status = str(data["status"])
+            if self.outer is None or (self.outer[0] == "workflow" and ps in (None, self.outer[1])):
+                self._end(ev)
+        elif et == "session_end":
+            self._end(ev)
+
+    def _end(self, ev: Dict[str, Any]) -> None:
+        self.ended = True
+        ts = ev.get("timestamp")
+        if isinstance(ts, (int, float)):
+            self.ended_at = float(ts)
+
+
+def find_graph(events: Iterable[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """The graph from the first ``workflow_start`` carrying one, else ``None``."""
+    for ev in events:
+        if ev.get("event_type") == "workflow_start":
+            data = ev.get("data")
+            if isinstance(data, dict) and isinstance(data.get("graph"), dict):
+                return data["graph"]
+    return None
+
+
+def _num(v: Any) -> float:
+    return float(v) if isinstance(v, (int, float)) and not isinstance(v, bool) else 0.0
+
+
+def summarize_run(path: Path, now: Optional[float] = None) -> Optional[Dict[str, Any]]:
+    """Run-picker row for one trace file (cached on mtime/size)."""
+    path = Path(path)
+    try:
+        st = path.stat()
+    except OSError:
+        return None
+    now = time.time() if now is None else now
+    sig = (st.st_mtime_ns, st.st_size, int(now - st.st_mtime < LIVE_WINDOW_S))
+    key = str(path)
+    with _CACHE_LOCK:
+        hit = _SUMMARY_CACHE.get(key)
+    if hit and hit[0] == sig:
+        return dict(hit[1])
+
+    events = read_events(path)
+    tracker = EndTracker()
+    agents: List[str] = []
+    cost = 0.0
+    session_id = None
+    event_run_id = None
+    started_at = None
+    kind, name, process = "session", None, None
+    schema = None
+    for ev in events:
+        tracker.feed(ev)
+        if session_id is None and ev.get("session_id"):
+            session_id = ev.get("session_id")
+        if event_run_id is None and ev.get("run_id"):
+            event_run_id = ev.get("run_id")
+        if schema is None and ev.get("schema_version"):
+            schema = str(ev.get("schema_version"))
+        ts = ev.get("timestamp")
+        if started_at is None and isinstance(ts, (int, float)):
+            started_at = float(ts)
+        agent = ev.get("agent_name")
+        if isinstance(agent, str) and agent and agent not in agents:
+            agents.append(agent)
+        cost += _num(ev.get("cost_usd"))
+        if ev.get("event_type") == "workflow_start" and name is None:
+            data = ev.get("data") if isinstance(ev.get("data"), dict) else {}
+            kind = str(data.get("kind") or "workflow")
+            name = data.get("name")
+            process = data.get("process")
+    live = (not tracker.ended) and (now - st.st_mtime) < LIVE_WINDOW_S
+    if tracker.ended:
+        status = tracker.status or "completed"
+    else:
+        status = "running" if live else "incomplete"
+    summary: Dict[str, Any] = {
+        "run_id": path.stem,
+        "session_id": session_id,
+        "path": str(path),
+        "started_at": started_at,
+        "status": status,
+        "kind": kind,
+        "name": name or (agents[0] if agents else path.stem),
+        "agents": agents,
+        "events": len(events),
+        "cost_usd": round(cost, 6),
+        "live": live,
+        "schema_version": schema,
+    }
+    if tracker.ended_at is not None:
+        summary["ended_at"] = tracker.ended_at
+    if process:
+        summary["process"] = process
+    if event_run_id and event_run_id != path.stem:
+        summary["event_run_id"] = event_run_id
+    with _CACHE_LOCK:
+        _SUMMARY_CACHE[key] = (sig, summary)
+        while len(_SUMMARY_CACHE) > _SUMMARY_CACHE_MAX:
+            _SUMMARY_CACHE.pop(next(iter(_SUMMARY_CACHE)))
+    return dict(summary)
+
+
+def _span_name(ev: Dict[str, Any]) -> str:
+    et = ev.get("event_type")
+    data = ev.get("data") if isinstance(ev.get("data"), dict) else {}
+    agent = ev.get("agent_name") or ""
+    if et == "tool_call_start":
+        return str(data.get("tool_name") or "tool")
+    if et == "llm_request":
+        model = data.get("model")
+        return f"llm {model}" if model else "llm"
+    if et == "approval_requested":
+        return f"approval {data.get('tool') or ''}".strip()
+    if et in ("task_start", "step_start", "workflow_start"):
+        return str(data.get("name") or ev.get("node_id") or et.split("_")[0])
+    if et == "agent_start":
+        return agent or "agent"
+    return "session"
+
+
+def _match_key(ev: Dict[str, Any]) -> Tuple[Any, ...]:
+    """Identity used to pair a start with its end when ``parent_seq`` is absent."""
+    et = ev.get("event_type")
+    data = ev.get("data") if isinstance(ev.get("data"), dict) else {}
+    base = END_START.get(et, et)
+    extra: Any = None
+    if base == "tool_call_start":
+        extra = data.get("tool_name")
+    elif base == "approval_requested":
+        extra = data.get("approval_id")
+    elif base in ("task_start", "step_start"):
+        extra = ev.get("node_id") or data.get("name")
+    agent = ev.get("agent_name") or ""
+    if base in ("approval_requested", "session_start", "workflow_start"):
+        agent = ""  # decisions/ends are often emitted by a different emitter name
+    return (base, agent, ev.get("branch_id"), extra)
+
+
+def build_spans(events: List[Dict[str, Any]], trace_id: str) -> List[Dict[str, Any]]:
+    """Spans from start/end pairs.
+
+    Schema 1.1: an end event's ``parent_seq`` names its start; a start's
+    ``parent_seq`` names the enclosing span.  Schema 1.0 (no ``parent_seq``):
+    ends pair with the oldest open start of the same kind/agent/tool, and the
+    parent is the innermost span open when the start was seen (sequence order).
+    ``llm_response`` is a point event whose ``parent_seq`` is its enclosing
+    scope, so LLM spans always pair by order.
+    """
+    ordered = sorted(enumerate(events), key=lambda it: (_seq(it[1], it[0]), it[0]))
+    spans: Dict[int, Dict[str, Any]] = {}
+    start_type: Dict[int, str] = {}
+    start_key: Dict[int, Tuple[Any, ...]] = {}
+    open_by_key: Dict[Tuple[Any, ...], List[int]] = {}
+    stack: List[int] = []
+    order: List[int] = []
+
+    for idx, ev in ordered:
+        et = ev.get("event_type")
+        seq = _seq(ev, idx)
+        ts = _num(ev.get("timestamp"))
+        if et in START_END:
+            parent = ev.get("parent_seq")
+            if not (isinstance(parent, int) and parent in spans):
+                parent = next((s for s in reversed(stack) if spans[s]["status"] == "open"), None)
+            data = ev.get("data") if isinstance(ev.get("data"), dict) else {}
+            span = {
+                "id": f"{trace_id}:{seq}",
+                "trace_id": trace_id,
+                "parent_span_id": f"{trace_id}:{parent}" if parent is not None else None,
+                "agent_id": ev.get("agent_name") or "",
+                "name": _span_name(ev),
+                "kind": _SPAN_KIND[et],
+                "status": "open",
+                "start_time": ts,
+                "end_time": None,
+                "duration_ms": None,
+                "timestamp": ts,
+                "attributes": {
+                    k: v
+                    for k, v in {
+                        "node_id": ev.get("node_id"),
+                        "branch_id": ev.get("branch_id"),
+                        "start_seq": seq,
+                        "input": data.get("tool_args") if et == "tool_call_start" else None,
+                    }.items()
+                    if v is not None
+                },
+                "events": [],
+            }
+            spans[seq] = span
+            start_type[seq] = et
+            start_key[seq] = _match_key(ev)
+            order.append(seq)
+            stack.append(seq)
+            open_by_key.setdefault(start_key[seq], []).append(seq)
+            continue
+        if et not in END_START:
+            continue
+        start_seq = None
+        ps = ev.get("parent_seq")
+        key = _match_key(ev)
+        if (
+            et != "llm_response"
+            and isinstance(ps, int)
+            and ps in spans
+            and spans[ps]["status"] == "open"
+            and START_END.get(start_type[ps]) == et
+        ):
+            start_seq = ps
+        else:
+            queue = open_by_key.get(key) or []
+            while queue and spans[queue[0]]["status"] != "open":
+                queue.pop(0)
+            if queue:
+                start_seq = queue[0]
+        if start_seq is None:
+            continue
+        q = open_by_key.get(start_key[start_seq])
+        if q and start_seq in q:
+            q.remove(start_seq)
+        span = spans[start_seq]
+        data = ev.get("data") if isinstance(ev.get("data"), dict) else {}
+        dur = data.get("duration_ms")
+        span["end_time"] = ts
+        span["duration_ms"] = (
+            float(dur) if isinstance(dur, (int, float)) and not isinstance(dur, bool)
+            else round(max(0.0, ts - span["start_time"]) * 1000, 3)
+        )
+        failed = bool(data.get("error")) or data.get("status") == "failed" or data.get("approved") is False
+        span["status"] = "error" if failed else "ok"
+        attrs = span["attributes"]
+        for k in ("cost_usd", "prompt_tokens", "completion_tokens"):
+            v = ev.get(k)
+            if isinstance(v, (int, float)) and not isinstance(v, bool) and v:
+                attrs[k] = v
+        if data.get("error"):
+            attrs["error"] = data.get("error")
+        if start_seq in stack:
+            stack.remove(start_seq)
+
+    return [spans[s] for s in order]
+

src/praisonaiui/features/approvals.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import threading
 import time
 import uuid
 from abc import ABC, abstractmethod
@@ -66,7 +67,13 @@ class ApprovalProtocol(ABC):
     @abstractmethod
     def approve(
         self, approval_id: str, reason: str = "", approver: str = "user", always: bool = False
-    ) -> Optional[Dict[str, Any]]: ...
+    ) -> Optional[Dict[str, Any]]:
+        """Approve a pending request.
+
+        Implementations may also accept ``modified_args: dict`` (replacement
+        tool arguments); the HTTP handler only passes it when the client sent it.
+        """
+        ...
 
     @abstractmethod
     def deny(
@@ -86,6 +93,66 @@ class ApprovalProtocol(ABC):
         return {"status": "ok", "provider": self.__class__.__name__}
 
 
+# ── Decision waiter ──────────────────────────────────────────────────
+
+
+class _DecisionWaiter:
+    """One pending decision that both threads and coroutines can wait on.
+
+    ``set()`` may be called from any thread (normally the server's event loop
+    handling ``POST /api/approvals/{id}/approve``); sync waiters block on a
+    ``threading.Event`` and async waiters get their future resolved on their
+    own loop via ``call_soon_threadsafe``, so neither blocks the other.
+    """
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+        self._lock = threading.Lock()
+        self._result: Optional[Dict[str, Any]] = None
+        self._futures: List[tuple] = []
+
+    @property
+    def done(self) -> bool:
+        return self._event.is_set()
+
+    def set(self, entry: Dict[str, Any]) -> None:
+        with self._lock:
+            if self._event.is_set():
+                return
+            self._result = entry
+            self._event.set()
+            futures, self._futures = self._futures, []
+        for loop, fut in futures:
+            try:
+                loop.call_soon_threadsafe(_resolve_future, fut, entry)
+            except RuntimeError:  # loop already closed
+                pass
+
+    def wait(self, timeout: Optional[float]) -> Optional[Dict[str, Any]]:
+        return self._result if self._event.wait(timeout) else None
+
+    async def wait_async(self, timeout: Optional[float]) -> Optional[Dict[str, Any]]:
+        loop = asyncio.get_running_loop()
+        fut = loop.create_future()
+        with self._lock:
+            if self._event.is_set():
+                return self._result
+            self._futures.append((loop, fut))
+        try:
+            return await asyncio.wait_for(fut, timeout)
+        except asyncio.TimeoutError:
+            return None
+        finally:
+            with self._lock:
+                if (loop, fut) in self._futures:
+                    self._futures.remove((loop, fut))
+
+
+def _resolve_future(fut: "asyncio.Future", value: Any) -> None:
+    if not fut.done():
+        fut.set_result(value)
+
+
 # ── Simple Approval Manager ──────────────────────────────────────────
 
 
@@ -95,6 +162,8 @@ class SimpleApprovalManager(ApprovalProtocol):
     def __init__(self) -> None:
         self._pending: Dict[str, Dict[str, Any]] = {}
         self._history: deque = deque(maxlen=500)
+        self._lock = threading.RLock()
+        self._waiters: Dict[str, _DecisionWaiter] = {}
         self._policies: Dict[str, Any] = {
             "auto_approve_tools": [],
             "always_deny_tools": [],
@@ -136,44 +205,67 @@ class SimpleApprovalManager(ApprovalProtocol):
             entry.get("agent_name", ""),
             entry.get("risk_level", "medium"),
         )
-        if auto:
-            entry["status"] = auto
-            entry["resolved_at"] = time.time()
-            entry["approver"] = "auto-policy"
-            entry["reason"] = f"Auto-{auto} by policy"
-            self._history.appendleft(entry)
-        else:
-            self._pending[approval_id] = entry
+        with self._lock:
+            if auto:
+                entry["status"] = auto
+                entry["resolved_at"] = time.time()
+                entry["approver"] = "auto-policy"
+                entry["reason"] = f"Auto-{auto} by policy"
+                self._history.appendleft(entry)
+            else:
+                self._pending[approval_id] = entry
+                self._waiters.setdefault(approval_id, _DecisionWaiter())
         return entry
 
+    def waiter(self, approval_id: str) -> Optional[_DecisionWaiter]:
+        """The waiter for a pending request (``None`` once it is resolved)."""
+        with self._lock:
+            return self._waiters.get(approval_id)
+
+    def _signal(self, approval_id: str, entry: Dict[str, Any]) -> None:
+        waiter = self._waiters.pop(approval_id, None)
+        if waiter is not None:
+            waiter.set(entry)
+
     def approve(
-        self, approval_id: str, reason: str = "", approver: str = "user", always: bool = False
+        self,
+        approval_id: str,
+        reason: str = "",
+        approver: str = "user",
+        always: bool = False,
+        modified_args: Optional[Dict[str, Any]] = None,
     ) -> Optional[Dict[str, Any]]:
-        if approval_id not in self._pending:
-            return None
-        entry = self._pending.pop(approval_id)
-        entry["status"] = "approved"
-        entry["reason"] = reason
-        entry["resolved_at"] = time.time()
-        entry["approver"] = approver
-        if always and entry["tool_name"] not in self._policies["auto_approve_tools"]:
-            self._policies["auto_approve_tools"].append(entry["tool_name"])
-        self._history.appendleft(entry)
+        with self._lock:
+            if approval_id not in self._pending:
+                return None
+            entry = self._pending.pop(approval_id)
+            entry["status"] = "approved"
+            entry["reason"] = reason
+            entry["resolved_at"] = time.time()
+            entry["approver"] = approver
+            if modified_args is not None:
+                entry["modified_args"] = dict(modified_args)
+            if always and entry["tool_name"] not in self._policies["auto_approve_tools"]:
+                self._policies["auto_approve_tools"].append(entry["tool_name"])
+            self._history.appendleft(entry)
+            self._signal(approval_id, entry)
         return entry
 
     def deny(
         self, approval_id: str, reason: str = "", approver: str = "user", always: bool = False
     ) -> Optional[Dict[str, Any]]:
-        if approval_id not in self._pending:
-            return None
-        entry = self._pending.pop(approval_id)
-        entry["status"] = "denied"
-        entry["reason"] = reason
-        entry["resolved_at"] = time.time()
-        entry["approver"] = approver
-        if always and entry["tool_name"] not in self._policies["always_deny_tools"]:
-            self._policies["always_deny_tools"].append(entry["tool_name"])
-        self._history.appendleft(entry)
+        with self._lock:
+            if approval_id not in self._pending:
+                return None
+            entry = self._pending.pop(approval_id)
+            entry["status"] = "denied"
+            entry["reason"] = reason
+            entry["resolved_at"] = time.time()
+            entry["approver"] = approver
+            if always and entry["tool_name"] not in self._policies["always_deny_tools"]:
+                self._policies["always_deny_tools"].append(entry["tool_name"])
+            self._history.appendleft(entry)
+            self._signal(approval_id, entry)
         return entry
 
     def get(self, approval_id: str) -> Optional[Dict[str, Any]]:
@@ -237,9 +329,14 @@ class SDKApprovalManager(ApprovalProtocol):
         return result
 
     def approve(
-        self, approval_id: str, reason: str = "", approver: str = "user", always: bool = False
+        self,
+        approval_id: str,
+        reason: str = "",
+        approver: str = "user",
+        always: bool = False,
+        modified_args: Optional[Dict[str, Any]] = None,
     ) -> Optional[Dict[str, Any]]:
-        entry = self._simple.approve(approval_id, reason, approver, always)
+        entry = self._simple.approve(approval_id, reason, approver, always, modified_args)
         if entry and always and entry.get("tool_name"):
             self._registry.add_requirement(entry["tool_name"], entry.get("risk_level", "high"))
         return entry
@@ -273,31 +370,121 @@ class SDKApprovalManager(ApprovalProtocol):
 
 
 class _UIStoreBackend:
-    """Routes agent approval requests into the UI SimpleApprovalManager."""
+    """Routes agent approval requests into the UI store and waits for a human.
 
-    def __init__(self, store: SimpleApprovalManager) -> None:
+    Each request becomes a pending entry keyed by ``request.approval_id`` and
+    the caller blocks (sync: on a ``threading.Event``; async: on a future of
+    its own loop) until ``POST /api/approvals/{id}/approve|deny`` resolves it.
+    No answer within the timeout is a denial (fail-closed) and the entry is
+    resolved as ``denied`` with ``approver="timeout"`` so the queue stays honest.
+    """
+
+    def __init__(self, store: SimpleApprovalManager, timeout: Optional[float] = None) -> None:
         self._store = store
+        self._timeout = timeout
 
-    def request_approval_sync(self, request) -> Any:
+    def _effective_timeout(self, timeout: Optional[float]) -> float:
+        if timeout is not None:
+            return float(timeout)
+        if self._timeout is not None:
+            return float(self._timeout)
+        try:
+            from praisonaiagents.approval import get_approval_registry
+
+            return float(getattr(get_approval_registry(), "timeout", 300.0))
+        except Exception:
+            return 300.0
+
+    def _submit(self, request) -> Dict[str, Any]:
+        entry: Dict[str, Any] = {
+            "tool_name": request.tool_name,
+            "agent_name": getattr(request, "agent_name", "") or "",
+            "risk_level": request.risk_level or "medium",
+            "arguments": request.arguments or {},
+        }
+        approval_id = getattr(request, "approval_id", None)
+        if approval_id:
+            entry["id"] = str(approval_id)
+        session_id = getattr(request, "session_id", None)
+        if session_id:
+            entry["session_id"] = session_id
+        return self._store.request_approval(entry)
+
+    @staticmethod
+    def _decision(entry: Optional[Dict[str, Any]]) -> Any:
         from praisonaiagents.approval.protocols import ApprovalDecision
 
-        entry = self._store.request_approval(
-            {
-                "tool_name": request.tool_name,
-                "agent_name": getattr(request, "agent_name", "") or "",
-                "risk_level": request.risk_level or "medium",
-                "arguments": request.arguments or {},
-            }
+        if entry is None:
+            return ApprovalDecision(
+                approved=False, reason="Timed out waiting for UI approval", approver="timeout"
+            )
+        if entry.get("status") == "approved":
+            return ApprovalDecision(
+                approved=True,
+                reason=entry.get("reason", ""),
+                modified_args=dict(entry.get("modified_args") or {}),
+                approver=entry.get("approver"),
+            )
+        return ApprovalDecision(
+            approved=False,
+            reason=entry.get("reason") or "denied",
+            approver=entry.get("approver"),
         )
-        status = entry.get("status", "pending")
-        if status == "approved":
-            return ApprovalDecision(approved=True, reason=entry.get("reason", ""))
-        if status == "denied":
-            return ApprovalDecision(approved=False, reason=entry.get("reason", "denied"))
-        return ApprovalDecision(approved=False, reason="Awaiting UI approval")
+
+    def _expire(
+        self,
+        approval_id: str,
+        reason: str = "Timed out waiting for UI approval",
+        approver: str = "timeout",
+    ) -> Optional[Dict[str, Any]]:
+        """Deny a request nobody answered; return the entry if a human won the race."""
+        denied = self._store.deny(approval_id, reason=reason, approver=approver)
+        if denied is not None:
+            return None
+        return self._store.get(approval_id)
+
+    def request_approval_sync(self, request, timeout: Optional[float] = None) -> Any:
+        from praisonaiagents.approval.protocols import ApprovalDecision
+
+        entry = self._submit(request)
+        if entry.get("status") != "pending":
+            return self._decision(entry)
+        approval_id = entry["id"]
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+        else:
+            # Blocking here would freeze this thread's event loop (and with it,
+            # possibly the very server that has to deliver the answer).
+            reason = "UI approval cannot block an event-loop thread; use the async approval path"
+            self._expire(approval_id, reason=reason, approver="ui")
+            return ApprovalDecision(approved=False, reason=reason, approver="ui")
+        waiter = self._store.waiter(approval_id)
+        result = waiter.wait(self._effective_timeout(timeout)) if waiter else self._store.get(approval_id)
+        if result is None:
+            result = self._expire(approval_id)
+        return self._decision(result)
 
     async def request_approval(self, request) -> Any:
-        return self.request_approval_sync(request)
+        entry = self._submit(request)
+        if entry.get("status") != "pending":
+            return self._decision(entry)
+        approval_id = entry["id"]
+        waiter = self._store.waiter(approval_id)
+        try:
+            result = (
+                await waiter.wait_async(self._effective_timeout(None))
+                if waiter
+                else self._store.get(approval_id)
+            )
+        except asyncio.CancelledError:
+            # The registry's own wait_for timed out (or the turn was cancelled).
+            self._expire(approval_id)
+            raise
+        if result is None:
+            result = self._expire(approval_id)
+        return self._decision(result)
 
 
 # ── Manager singleton ────────────────────────────────────────────────
@@ -449,11 +636,15 @@ class ApprovalsFeature(BaseFeatureProtocol):
         mgr = get_approval_manager()
         approval_id = request.path_params["approval_id"]
         body = await request.json() if request.headers.get("content-length") else {}
+        modified_args = body.get("modified_args")
+        if modified_args is not None and not isinstance(modified_args, dict):
+            return JSONResponse({"error": "modified_args must be an object"}, status_code=400)
         entry = mgr.approve(
             approval_id,
             reason=body.get("reason", ""),
             approver=body.get("approver", "user"),
             always=body.get("always", False),
+            **({"modified_args": modified_args} if modified_args is not None else {}),
         )
         if entry is None:
             return JSONResponse({"error": "Approval not found"}, status_code=404)

src/praisonaiui/features/replay.py

@@ -0,0 +1,441 @@
+"""PraisonAI Replay feature: read-only access to recorded agent runs.
+
+Routes (contract v1, section 5):
+
+* ``GET /api/replay/runs``                       run picker rows, newest first
+* ``GET /api/replay/runs/{run_id}/events``       ``{events, graph, run}``; ``?after_seq=N``;
+  ``?wait=1`` answers ``{events: [], graph: null, run: null}`` (not 404) for a run
+  that has not written its first event yet
+* ``GET /api/replay/runs/{run_id}/stream``       SSE tail of the JSONL file
+
+The trace directory is ``$PRAISONAI_TRACES_DIR``, else ``$PRAISON_HOME/traces``,
+else ``~/.praison/traces``.  Run ids must match ``^[A-Za-z0-9._-]+$``.
+
+The browser side lives in ``templates/frontend/plugins/views/replay-core.js``
+(pure functions) and ``replay.js`` (DOM/SVG).  :func:`standalone_html` inlines
+both into one self-contained page for ``praisonai replay export --format html``.
+
+:func:`create_replay_app` is the same view as a small ASGI app (no dashboard) to
+mount inside your own app, optionally with a Run box that starts runs::
+
+    app.mount("/replay", create_replay_app(run=my_runner))
+"""
+
+from __future__ import annotations
+
+import asyncio
+import html
+import inspect
+import json
+import logging
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+from urllib.parse import quote
+
+from starlette.concurrency import run_in_threadpool
+from starlette.requests import Request
+from starlette.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
+from starlette.routing import Route
+
+from . import _trace_jsonl as tj
+from ._base import BaseFeatureProtocol
+
+logger = logging.getLogger(__name__)
+
+#: Page id of the dashboard view; open ``/replay?run=<id>`` (or ``/#/replay?run=<id>``).
+REPLAY_PAGE_ID = "replay"
+
+#: Replay's own mark (three lanes and a cursor), used as the page's ``icon_svg``.
+REPLAY_MARK_SVG = (
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="1em" height="1em" '
+    'aria-hidden="true" focusable="false" '
+    'style="display:inline-block;vertical-align:-0.125em">'
+    '<rect x="1" y="3" width="8" height="2.2" rx="1.1" fill="currentColor"/>'
+    '<rect x="3" y="7" width="10" height="2.2" rx="1.1" fill="currentColor"/>'
+    '<rect x="1" y="11" width="6" height="2.2" rx="1.1" fill="currentColor"/>'
+    '<rect x="11.2" y="1" width="1.6" height="14" rx="0.8" fill="currentColor" opacity="0.55"/>'
+    "</svg>"
+)
+
+#: Pages a replay-only app should whitelist (Replay first, then its companions).
+REPLAY_PAGES = ("replay", "approvals", "traces")
+
+_VIEWS_DIR = Path(__file__).resolve().parent.parent / "templates" / "frontend" / "plugins" / "views"
+#: Stable on-disk locations of the renderer (also served at /plugins/views/...).
+REPLAY_CORE_JS = _VIEWS_DIR / "replay-core.js"
+REPLAY_VIEW_JS = _VIEWS_DIR / "replay.js"
+
+
+def configure_replay_app() -> None:
+    """Configure aiui as a Replay-first dashboard (call before the server starts).
+
+    Equivalent to ``aiui.set_style("dashboard")`` plus
+    ``aiui.set_pages(["replay", "approvals", "traces"])``; Replay sorts first,
+    so ``/`` lands on it.  Used by ``praisonaiui/replay_app.py``.
+    """
+    from praisonaiui.server import set_pages, set_style
+
+    set_style("dashboard")
+    set_pages(list(REPLAY_PAGES))
+
+
+def _json_for_script(obj: Any) -> str:
+    """JSON that is safe inside an inline ``<script>`` element."""
+    text = json.dumps(obj, default=str, separators=(",", ":"))
+    return (
+        text.replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("&", "\\u0026")
+        .replace("\u2028", "\\u2028")
+        .replace("\u2029", "\\u2029")
+    )
+
+
+def standalone_html(
+    events: List[Dict[str, Any]],
+    graph: Optional[Dict[str, Any]] = None,
+    title: str = "PraisonAI Replay",
+) -> str:
+    """One self-contained HTML page (no CDN, no network) rendering *events*.
+
+    Inlines ``replay-core.js`` and ``replay.js`` and sets
+    ``window.__REPLAY_DATA__ = {events, graph}``; the view boots itself.
+    Approval buttons are hidden because there is no server to answer them.
+    """
+    core = REPLAY_CORE_JS.read_text(encoding="utf-8").replace("</script", "<\\/script")
+    view = REPLAY_VIEW_JS.read_text(encoding="utf-8").replace("</script", "<\\/script")
+    if graph is None:
+        graph = tj.find_graph(events)
+    data = _json_for_script({"events": list(events), "graph": graph})
+    safe_title = (
+        str(title).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    )
+    return (
+        "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n"
+        "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n"
+        f"<title>{safe_title}</title>\n"
+        "<style>body{margin:0;font-family:system-ui,-apple-system,'Segoe UI',sans-serif}</style>\n"
+        "</head>\n<body>\n<main id=\"replay-root\"></main>\n"
+        f"<script>window.__REPLAY_DATA__ = {data};</script>\n"
+        f"<script type=\"module\">\n{core}\n</script>\n"
+        f"<script type=\"module\">\n{view}\n</script>\n"
+        "</body>\n</html>\n"
+    )
+
+
+def _bad_request(msg: str) -> JSONResponse:
+    return JSONResponse({"error": msg}, status_code=400)
+
+
+def _parse_after_seq(request: Request) -> tuple[Optional[int], Optional[JSONResponse]]:
+    """``?after_seq=N``; an SSE reconnect's ``Last-Event-ID`` wins when it is later."""
+    values = []
+    for raw, strict in (
+        (request.query_params.get("after_seq"), True),
+        (request.headers.get("last-event-id"), False),
+    ):
+        if raw in (None, ""):
+            continue
+        try:
+            values.append(int(raw))
+        except (TypeError, ValueError):
+            if strict:
+                return None, _bad_request("after_seq must be an integer")
+    return (max(values) if values else None), None
+
+
+def _resolve(request: Request) -> tuple[Optional[Path], Optional[JSONResponse]]:
+    run_id = request.path_params.get("run_id", "")
+    path = tj.run_path(run_id)
+    if path is None:
+        return None, _bad_request("invalid run id (allowed: A-Z a-z 0-9 . _ -)")
+    if not path.is_file():
+        return None, JSONResponse({"error": "run not found"}, status_code=404)
+    return path, None
+
+
+def _seq_of(ev: Dict[str, Any]) -> Optional[int]:
+    s = ev.get("sequence_num")
+    return s if isinstance(s, int) and not isinstance(s, bool) else None
+
+
+class ReplayFeature(BaseFeatureProtocol):
+    """Recorded-run timeline, map and live tail (PraisonAI Replay)."""
+
+    feature_name = "replay"
+    feature_description = "Replay recorded agent runs (timeline, map, live tail)"
+
+    # Stream timings; instance attributes so tests can shorten them.
+    poll_interval = 0.25
+    ping_interval = 15.0
+    quiet_period = 2.0
+
+    @property
+    def name(self) -> str:
+        return self.feature_name
+
+    @property
+    def description(self) -> str:
+        return self.feature_description
+
+    def routes(self) -> List[Route]:
+        return [
+            Route("/api/replay/runs", self._runs, methods=["GET"]),
+            Route("/api/replay/runs/{run_id}/events", self._events, methods=["GET"]),
+            Route("/api/replay/runs/{run_id}/stream", self._stream, methods=["GET"]),
+        ]
+
+    async def health(self) -> Dict[str, Any]:
+        d = tj.traces_dir()
+        return {
+            "status": "ok",
+            "feature": self.name,
+            "traces_dir": str(d),
+            "runs": len(tj.list_run_files(d)),
+        }
+
+    def cli_commands(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "name": "replay",
+                "help": "List recorded runs (PraisonAI Replay)",
+                "commands": {"list": {"help": "List recorded runs", "handler": self._cli_list}},
+            }
+        ]
+
+    # ── data ──────────────────────────────────────────────────────────
+
+    @staticmethod
+    def list_runs(limit: int = 200) -> List[Dict[str, Any]]:
+        rows = []
+        now = time.time()
+        for path in tj.list_run_files()[: max(1, limit)]:
+            row = tj.summarize_run(path, now=now)
+            if row is not None:
+                rows.append(row)
+        rows.sort(key=lambda r: (r.get("started_at") or 0.0, r["run_id"]), reverse=True)
+        return rows
+
+    def _cli_list(self) -> str:
+        rows = self.list_runs()
+        if not rows:
+            return f"No recorded runs in {tj.traces_dir()}"
+        lines = [f"Runs ({len(rows)}):"]
+        for r in rows:
+            live = " LIVE" if r.get("live") else ""
+            lines.append(
+                f"  {r['run_id']}  {r.get('name')}  {r['status']}{live}  "
+                f"events={r['events']}  ${r['cost_usd']:.4f}"
+            )
+        return "\n".join(lines)
+
+    # ── handlers ──────────────────────────────────────────────────────
+
+    async def _runs(self, request: Request) -> JSONResponse:
+        try:
+            limit = int(request.query_params.get("limit", "200"))
+        except ValueError:
+            return _bad_request("limit must be an integer")
+        rows = await run_in_threadpool(self.list_runs, limit)
+        return JSONResponse(rows)
+
+    async def _events(self, request: Request) -> JSONResponse:
+        path, err = _resolve(request)
+        if err is not None:
+            if err.status_code == 404 and request.query_params.get("wait") == "1":
+                return JSONResponse({"events": [], "graph": None, "run": None})
+            return err
+        after_seq, err = _parse_after_seq(request)
+        if err is not None:
+            return err
+
+        def load() -> Dict[str, Any]:
+            all_events = tj.read_events(path)
+            events = all_events if after_seq is None else tj.read_events(path, after_seq)
+            return {
+                "events": events,
+                "graph": tj.find_graph(all_events),
+                "run": tj.summarize_run(path),
+            }
+
+        return JSONResponse(await run_in_threadpool(load))
+
+    async def _stream(self, request: Request) -> StreamingResponse:
+        path, err = _resolve(request)
+        if err is not None:
+            return err  # type: ignore[return-value]
+        after_seq, err = _parse_after_seq(request)
+        if err is not None:
+            return err  # type: ignore[return-value]
+
+        poll, ping, quiet = self.poll_interval, self.ping_interval, self.quiet_period
+
+        async def gen():
+            tail = tj.TailReader(path)
+            tracker = tj.EndTracker()
+            last_seq = after_seq
+            loop = asyncio.get_running_loop()
+            last_activity = last_ping = loop.time()
+            yield "retry: 3000\n\n"
+            while True:
+                events = await run_in_threadpool(tail.poll)
+                now = loop.time()
+                if events:
+                    last_activity = now
+                for ev in events:
+                    tracker.feed(ev)
+                    seq = _seq_of(ev)
+                    if last_seq is not None and seq is not None and seq <= last_seq:
+                        continue
+                    if seq is not None:
+                        last_seq = seq
+                    sid = f"id: {seq}\n" if seq is not None else ""
+                    yield f"{sid}event: ctx\ndata: {json.dumps(ev, default=str)}\n\n"
+                idle = now - last_activity
+                if tracker.ended and idle >= quiet:
+                    yield "event: end\ndata: {}\n\n"
+                    return
+                if not path.exists() or idle >= tj.LIVE_WINDOW_S:
+                    yield 'event: end\ndata: {"reason": "stale"}\n\n'
+                    return
+                if now - last_ping >= ping:
+                    last_ping = now
+                    yield "event: ping\ndata: {}\n\n"
+                await asyncio.sleep(poll)
+
+        return StreamingResponse(
+            gen(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no"},
+        )
+
+
+# ── embeddable app ─────────────────────────────────────────────────────
+
+#: Longest input the Run box accepts (characters).
+MAX_RUN_INPUT = 20_000
+
+
+def _embed_page(base: str, title: str, cfg: Dict[str, Any]) -> str:
+    """The page at the app's root: the view, mounted with *cfg*, and nothing else."""
+    return (
+        "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n"
+        "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n"
+        f"<title>{html.escape(title)}</title>\n"
+        f"<link rel=\"icon\" href=\"data:image/svg+xml,{quote(REPLAY_MARK_SVG.replace('currentColor', '#1A56DB'))}\">\n"
+        "<style>body{margin:0;font-family:system-ui,-apple-system,'Segoe UI',sans-serif}"
+        "#replay-root{padding:12px;box-sizing:border-box;max-width:100%}</style>\n"
+        "</head>\n<body>\n<main id=\"replay-root\"></main>\n"
+        "<script type=\"module\">\n"
+        f"import {{ render }} from {_json_for_script(base + '/replay.js')};\n"
+        f"render(document.getElementById('replay-root'), {_json_for_script(cfg)});\n"
+        "</script>\n</body>\n</html>\n"
+    )
+
+
+def create_replay_app(
+    run: Optional[Callable[[str, str], Any]] = None,
+    *,
+    title: str = "PraisonAI Replay",
+    input: Optional[str] = "",
+    placeholder: str = "",
+):
+    """PraisonAI Replay as a small ASGI app to mount in your own app.
+
+    Serves the view at ``/`` (no dashboard around it), its two scripts, and the
+    ``/api/replay/...`` routes, all relative to where it is mounted::
+
+        from fastapi import FastAPI
+        from praisonaiui.features.replay import create_replay_app
+
+        app = FastAPI()
+        app.mount("/replay", create_replay_app())
+        # <iframe src="/replay/?run=RUN_ID"> shows one run live; /replay/ lists runs
+
+    Args:
+        run: Optional ``run(input, run_id)``. When given, the page shows an
+            input box and a **Run** button; each click calls it in a worker
+            thread with a new ``run_id``, and the page follows that run live.
+            It must record the run under ``run_id`` (``praisonai.replay.app()``
+            does this for an agent, team or flow). One run at a time.
+        title: Page title.
+        input: Text the input box starts with; ``None`` for no input box
+            (just a Run button, e.g. for a YAML file that has its own topic).
+        placeholder: Placeholder text for the input box.
+
+    Traces are read from the same folder as the rest of Replay
+    (``$PRAISONAI_TRACES_DIR`` > ``$PRAISON_HOME/traces`` > ``~/.praison/traces``).
+    Anyone who can reach the app can read the runs (and, with ``run``, start
+    them): keep it on localhost or behind your app's auth.
+    """
+    from starlette.applications import Starlette
+
+    feature = ReplayFeature()
+    busy = threading.Lock()
+
+    async def page(request: Request) -> HTMLResponse:
+        base = str(request.scope.get("root_path", "")).rstrip("/")
+        cfg: Dict[str, Any] = {"base": base, "approve": False}
+        wanted = request.query_params.get("run")
+        if wanted and tj.is_valid_run_id(wanted):
+            cfg["run"] = wanted
+        if run is not None:
+            cfg["runner"] = {"input": input or "", "placeholder": placeholder, "ask": input is not None}
+        return HTMLResponse(_embed_page(base, title, cfg), headers={"Cache-Control": "no-store"})
+
+    def script(path: Path):
+        async def serve(request: Request) -> FileResponse:
+            return FileResponse(path, media_type="text/javascript", headers={"Cache-Control": "no-cache"})
+        return serve
+
+    def _call(text: str, run_id: str) -> None:
+        try:
+            result = run(text, run_id)  # type: ignore[misc]
+            if inspect.isawaitable(result):
+                asyncio.run(result)
+        except Exception:
+            logger.exception("replay run %s failed", run_id)
+        finally:
+            busy.release()
+
+    async def start(request: Request) -> JSONResponse:
+        # JSON only: a cross-site form post cannot set this content type without
+        # a CORS preflight, which this app never answers.
+        if not request.headers.get("content-type", "").lower().startswith("application/json"):
+            return JSONResponse({"error": "send JSON: {\"input\": \"...\"}"}, status_code=415)
+        try:
+            body = await request.json()
+        except ValueError:
+            return _bad_request("body must be JSON")
+        text = body.get("input", "") if isinstance(body, dict) else None
+        if not isinstance(text, str) or len(text) > MAX_RUN_INPUT:
+            return _bad_request(f"input must be a string of at most {MAX_RUN_INPUT} characters")
+        if not busy.acquire(blocking=False):
+            return JSONResponse({"error": "a run is already going; wait for it to finish"}, status_code=409)
+        run_id = f"run-{uuid.uuid4().hex[:12]}"
+        try:
+            threading.Thread(target=_call, args=(text, run_id), name=f"replay-{run_id}", daemon=True).start()
+        except Exception:
+            busy.release()
+            raise
+        # Answer once the trace file exists (usually milliseconds), so the page
+        # can open the run straight away; it waits on its own if this times out.
+        path = tj.run_path(run_id)
+        for _ in range(40):
+            if path is not None and path.is_file():
+                break
+            await asyncio.sleep(0.05)
+        return JSONResponse({"run_id": run_id})
+
+    routes = [
+        Route("/", page, methods=["GET"]),
+        Route("/replay.js", script(REPLAY_VIEW_JS), methods=["GET"]),
+        Route("/replay-core.js", script(REPLAY_CORE_JS), methods=["GET"]),
+        *feature.routes(),
+    ]
+    if run is not None:
+        routes.append(Route("/api/replay/run", start, methods=["POST"]))
+    return Starlette(routes=routes)

src/praisonaiui/features/tracing.py

@@ -2,8 +2,8 @@
 
 Architecture:
     TracingProtocol (ABC)          <- any backend implements this
-      ├── SimpleTracingManager     <- default in-memory (no deps)
-      └── SDKTracingManager        <- wraps praisonaiagents.obs + trace
+      ├── SimpleTracingManager     <- in-memory (no deps)
+      └── JsonlTracingManager      <- recorded runs (context-trace JSONL) + in-memory
 
     PraisonAITracing (BaseFeatureProtocol)
       └── delegates to active TracingProtocol implementation
@@ -110,56 +110,112 @@ class SimpleTracingManager(TracingProtocol):
         }
 
 
-# ── SDK Tracing Manager ──────────────────────────────────────────────
+# ── JSONL Tracing Manager ────────────────────────────────────────────
 
 
-class SDKTracingManager(TracingProtocol):
-    """Wraps praisonaiagents.obs + trace for production use."""
+class JsonlTracingManager(TracingProtocol):
+    """Reads recorded runs from the context-trace JSONL directory.
+
+    One ``<id>.jsonl`` file is one trace; spans come from start/end event
+    pairs (``parent_seq`` on schema 1.1, sequence order on 1.0).  The
+    directory is ``$PRAISONAI_TRACES_DIR`` > ``$PRAISON_HOME/traces`` >
+    ``~/.praison/traces`` (shared with the ``replay`` feature).  Traces and
+    spans posted to ``/api/traces/record`` stay in memory alongside.
+    """
+
+    #: Upper bound on files scanned for an unfiltered span listing.
+    MAX_FILES_FOR_SPANS = 20
 
     def __init__(self) -> None:
-        self._trace_available = False
-        self._obs_available = False
-        try:
-            from praisonaiagents.trace import ActionEvent  # noqa: F401
-
-            self._trace_available = True
-        except (ImportError, AttributeError):
-            pass
-        try:
-            from praisonaiagents.obs import Span, Trace  # noqa: F401
-
-            self._obs_available = True
-        except ImportError:
-            pass
-        if not (self._trace_available or self._obs_available):
-            raise ImportError("Neither praisonaiagents.trace nor praisonaiagents.obs available")
         self._simple = SimpleTracingManager()
-        logger.info(
-            "SDKTracingManager initialized (trace=%s, obs=%s)",
-            self._trace_available,
-            self._obs_available,
+
+    # -- JSONL side ---------------------------------------------------
+
+    @staticmethod
+    def _trace_from_file(path) -> Optional[Dict[str, Any]]:
+        from . import _trace_jsonl as tj
+
+        row = tj.summarize_run(path)
+        if row is None:
+            return None
+        events = tj.read_events(path)
+        started = row.get("started_at") or 0.0
+        ended = row.get("ended_at")
+        last_ts = max(
+            (e["timestamp"] for e in events if isinstance(e.get("timestamp"), (int, float))),
+            default=started,
         )
+        agents = row.get("agents") or []
+        return {
+            "id": row["run_id"],
+            "agent_id": agents[0] if agents else "",
+            "agents": agents,
+            "name": row.get("name") or row["run_id"],
+            "status": row["status"],
+            "start_time": started,
+            "end_time": ended,
+            "timestamp": started,
+            "duration_ms": round(((ended or last_ts) - started) * 1000, 3),
+            "span_count": len(tj.build_spans(events, row["run_id"])),
+            "source": "jsonl",
+            "metadata": {
+                "path": row["path"],
+                "session_id": row.get("session_id"),
+                "kind": row.get("kind"),
+                "events": row["events"],
+                "cost_usd": row["cost_usd"],
+                "live": row["live"],
+            },
+        }
+
+    @staticmethod
+    def _files():
+        from . import _trace_jsonl as tj
+
+        return tj.list_run_files()
 
     def list_traces(
         self, *, limit: int = 50, agent_id: Optional[str] = None
     ) -> List[Dict[str, Any]]:
-        sdk_traces = self._list_traces_from_sdk(limit=limit, agent_id=agent_id)
-        if sdk_traces is not None:
-            return sdk_traces
-        return self._simple.list_traces(limit=limit, agent_id=agent_id)
+        items: List[Dict[str, Any]] = []
+        for path in self._files():
+            if len(items) >= limit:
+                break
+            trace = self._trace_from_file(path)
+            if trace is None:
+                continue
+            if agent_id and agent_id not in trace["agents"]:
+                continue
+            items.append(trace)
+        remaining = max(0, limit - len(items))
+        if remaining:
+            items.extend(self._simple.list_traces(limit=remaining, agent_id=agent_id))
+        return items
 
     def list_spans(
         self, *, limit: int = 100, trace_id: Optional[str] = None
     ) -> List[Dict[str, Any]]:
-        sdk_spans = self._list_spans_from_sdk(limit=limit, trace_id=trace_id)
-        if sdk_spans is not None:
-            return sdk_spans
-        return self._simple.list_spans(limit=limit, trace_id=trace_id)
+        from . import _trace_jsonl as tj
+
+        if trace_id:
+            path = tj.run_path(trace_id)
+            if path is not None and path.is_file():
+                return tj.build_spans(tj.read_events(path), trace_id)[:limit]
+            return self._simple.list_spans(limit=limit, trace_id=trace_id)
+        spans: List[Dict[str, Any]] = []
+        for path in self._files()[: self.MAX_FILES_FOR_SPANS]:
+            spans.extend(tj.build_spans(tj.read_events(path), path.stem))
+            if len(spans) >= limit:
+                return spans[:limit]
+        spans.extend(self._simple.list_spans(limit=limit - len(spans)))
+        return spans[:limit]
 
     def get_trace(self, trace_id: str) -> Optional[Dict[str, Any]]:
-        sdk_trace = self._get_trace_from_sdk(trace_id)
-        if sdk_trace is not None:
-            return sdk_trace
+        from . import _trace_jsonl as tj
+
+        path = tj.run_path(trace_id)
+        if path is not None and path.is_file():
+            return self._trace_from_file(path)
         return self._simple.get_trace(trace_id)
 
     def record_trace(self, trace: Dict[str, Any]) -> str:
@@ -168,69 +224,34 @@ class SDKTracingManager(TracingProtocol):
     def record_span(self, span: Dict[str, Any]) -> str:
         return self._simple.record_span(span)
 
-    def _list_traces_from_sdk(
-        self, *, limit: int, agent_id: Optional[str]
-    ) -> Optional[List[Dict[str, Any]]]:
-        try:
-            from praisonaiagents import trace as trace_module
-
-            getter = getattr(trace_module, "list_traces", None)
-            if not callable(getter):
-                return None
-            items = getter(limit=limit, agent_id=agent_id)
-            return items if isinstance(items, list) else None
-        except Exception:
-            return None
-
-    def _list_spans_from_sdk(
-        self, *, limit: int, trace_id: Optional[str]
-    ) -> Optional[List[Dict[str, Any]]]:
-        try:
-            from praisonaiagents import trace as trace_module
-
-            getter = getattr(trace_module, "list_spans", None)
-            if not callable(getter):
-                return None
-            items = getter(limit=limit, trace_id=trace_id)
-            return items if isinstance(items, list) else None
-        except Exception:
-            return None
-
-    def _get_trace_from_sdk(self, trace_id: str) -> Optional[Dict[str, Any]]:
-        try:
-            from praisonaiagents import trace as trace_module
-
-            getter = getattr(trace_module, "get_trace", None)
-            if not callable(getter):
-                return None
-            trace = getter(trace_id)
-            return trace if isinstance(trace, dict) else None
-        except Exception:
-            return None
-
     def health(self) -> Dict[str, Any]:
+        from . import _trace_jsonl as tj
+
         h = self._simple.health()
-        h["provider"] = "SDKTracingManager"
-        h["trace_available"] = self._trace_available
-        h["obs_available"] = self._obs_available
+        files = self._files()
+        h["provider"] = self.__class__.__name__
+        h["source"] = "jsonl" if files else "memory"
+        h["traces_dir"] = str(tj.traces_dir())
+        h["jsonl_traces"] = len(files)
         return h
 
 
+#: Deprecated alias. The old class looked up ``praisonaiagents.trace.list_traces``
+#: / ``list_spans`` / ``get_trace``, which never existed, so it always fell back
+#: to the in-memory store.  Recorded runs are JSONL files; read those instead.
+SDKTracingManager = JsonlTracingManager
+
+
 # ── Manager singleton ────────────────────────────────────────────────
 
 _tracing_manager: Optional[TracingProtocol] = None
 
 
 def get_tracing_manager() -> TracingProtocol:
-    """Get the active tracing manager (SDK-first, fallback to Simple)."""
+    """Get the active tracing manager (recorded JSONL runs + in-memory records)."""
     global _tracing_manager
     if _tracing_manager is None:
-        try:
-            _tracing_manager = SDKTracingManager()
-            logger.info("Using SDKTracingManager")
-        except Exception as e:
-            logger.debug("SDKTracingManager init failed (%s), using SimpleTracingManager", e)
-            _tracing_manager = SimpleTracingManager()
+        _tracing_manager = JsonlTracingManager()
     return _tracing_manager
 
 
@@ -301,12 +322,10 @@ class TracingFeature(BaseFeatureProtocol):
         h = mgr.health()
         lines = ["Tracing Status:"]
         lines.append(f"  Provider: {h.get('provider', 'unknown')}")
+        if "source" in h:
+            lines.append(f"  Source: {h['source']} ({h.get('traces_dir', '')})")
         lines.append(f"  Total traces: {h.get('total_traces', 0)}")
         lines.append(f"  Total spans: {h.get('total_spans', 0)}")
-        if "trace_available" in h:
-            lines.append(f"  SDK trace: {'available' if h['trace_available'] else 'unavailable'}")
-        if "obs_available" in h:
-            lines.append(f"  SDK obs: {'available' if h['obs_available'] else 'unavailable'}")
         return "\n".join(lines)
 
     def _cli_list(self, limit: int = 20) -> str:

src/praisonaiui/replay_app.py

@@ -0,0 +1,15 @@
+"""Ready-made aiui app that opens straight to PraisonAI Replay.
+
+Usage (what ``praisonai replay view`` runs)::
+
+    aiui run "$(python -c 'import praisonaiui.replay_app as m; print(m.__file__)')" \
+        --style dashboard --host 127.0.0.1 --port 8090
+
+then open ``http://127.0.0.1:8090/replay?run=<run_id>`` (``/#/replay?run=<run_id>``
+is accepted too).  The trace directory follows ``PRAISONAI_TRACES_DIR`` >
+``PRAISON_HOME/traces`` > ``~/.praison/traces``.
+"""
+
+from praisonaiui.features.replay import configure_replay_app
+
+configure_replay_app()

src/praisonaiui/server.py

@@ -1303,9 +1303,11 @@ async def patch_session(request: Request) -> JSONResponse:
         body = await request.json()
     except Exception:
         return JSONResponse({"error": "Invalid JSON"}, status_code=400)
-    title = body.get("title")
+    title = body.get("title") if isinstance(body, dict) else None
     if title is not None:
-        await _datastore.update_session(session_id, title=title)
+        if not isinstance(title, str) or not title.strip():
+            return JSONResponse({"error": "title must be a non-empty string"}, status_code=400)
+        await _datastore.update_session(session_id, title=title.strip()[:200])
     return JSONResponse({"status": "updated", "session_id": session_id})
 
 
@@ -3280,6 +3282,8 @@ def create_app(
         routes.extend(feature.routes())
 
     # Register built-in dashboard pages via the same protocol
+    from praisonaiui.features.replay import REPLAY_MARK_SVG
+
     _builtin_pages = [
         {
             "id": "overview",
@@ -3296,6 +3300,7 @@ def create_app(
             "group": "Agent",
             "description": "AI agent chat",
             "order": 1,
+            "layout": "full-bleed",
         },
         {
             "id": "chat-canvas",
@@ -3304,6 +3309,7 @@ def create_app(
             "group": "Agent",
             "description": "Chat with live A2UI preview panel",
             "order": 2,
+            "layout": "full-bleed",
         },
         {
             "id": "canvas",
@@ -3345,6 +3351,15 @@ def create_app(
             "description": "Run flight recorder — timeline debugger",
             "order": 22,
         },
+        {
+            "id": "replay",
+            "title": "Replay",
+            "icon": "⏮️",
+            "icon_svg": REPLAY_MARK_SVG,
+            "group": "Control",
+            "description": "Recorded agent runs, step by step: who did what, when, and at what cost",
+            "order": 21,
+        },
         {
             "id": "usage",
             "title": "Usage",
@@ -3582,6 +3597,7 @@ def create_app(
     _page_api_overrides = {
         "sessions": "/sessions",
         "runs": "/api/sessions",
+        "replay": "/api/replay/runs",
         "cron": "/api/schedules",
         "channels": "/api/channels",
         "mcp": "/api/mcp/servers",

src/praisonaiui/templates/frontend/plugins/dashboard.js

@@ -147,6 +147,7 @@ const BUILTIN_VIEWS = {
   agents:         '/plugins/views/agents.js',
   sessions:       '/plugins/views/sessions.js',
   runs:           '/plugins/views/run-recorder.js',
+  replay:         '/plugins/views/replay.js',
   memory:         '/plugins/views/memory.js',
   knowledge:      '/plugins/views/knowledge.js',
   logs:           '/plugins/views/logs.js',
@@ -377,8 +378,12 @@ const DASHBOARD_STYLE = `
   .db-main { flex: 1; padding: 32px 40px; overflow-y: auto; min-width: 0; }
   .db-main.db-clean { padding: 0; display: flex; flex-direction: column; overflow: hidden; height: 100vh; }
   .db-main.db-clean > #db-page-content { flex: 1; display: flex; flex-direction: column; min-height: 0; }
+  /* Per-page full bleed (page.layout === 'full-bleed'): view fills the main column. */
+  .db-main.db-fill { display: flex; flex-direction: column; overflow: hidden; height: 100vh; box-sizing: border-box; }
+  .db-main.db-fill > #db-page-content { flex: 1; display: flex; flex-direction: column; min-height: 0; }
   .db-page-header { margin-bottom: 28px; }
   .db-page-title { font-size: 26px; font-weight: 700; letter-spacing: -0.02em; margin: 0 0 4px; }
+  .db-page-icon svg, .db-nav-icon svg { display: inline-block; vertical-align: -0.125em; }
   .db-page-desc { color: var(--db-text-dim); font-size: 14px; margin: 0; }
 
   /* Generic data viewer */
@@ -457,10 +462,20 @@ const DASHBOARD_STYLE = `
   .db-mobile-overlay { display: none; position: fixed; inset: 0; z-index: 35; background: rgba(0,0,0,0.5); }
   @media (max-width: 1023px) {
     .db-mobile-header { display: flex; }
-    .db-sidebar { position: fixed; z-index: 45; transform: translateX(-100%); transition: transform 0.2s ease; }
+    /* !important: buildSidebar() sets an inline position:relative for its toggle,
+       which otherwise keeps the hidden sidebar's 260px in the flex row. */
+    .db-sidebar { position: fixed !important; top: 0; left: 0; z-index: 45; transform: translateX(-100%); transition: transform 0.2s ease; }
     .db-sidebar.db-sidebar-open { transform: translateX(0); }
     .db-mobile-overlay.db-visible { display: block; }
     .db-main { padding-top: 48px; }
+    /* The shell header slot sits in the same flex row; give it its own line. */
+    #root.db-active { flex-wrap: wrap; }
+    #db-shell-header-slot { flex: 0 0 100%; margin-top: 48px; }
+    #db-shell-header-slot + .db-main { padding-top: 16px; }
+  }
+  @media (max-width: 600px) {
+    .db-main { padding: 64px 16px 16px; }
+    #db-shell-header-slot + .db-main { padding-top: 16px; }
   }
   .db-card {
     background: var(--db-card-bg); border: 1px solid var(--db-border);
@@ -1752,6 +1767,13 @@ async function buildDashboard() {
   renderSlot('shell:header', shellHeader);
   if (shellHeader.children.length) root.insertBefore(shellHeader, main);
 
+  // Hash deep links (e.g. /#/replay?run=<id> from `praisonai replay view`)
+  // become the path form (/replay?run=<id>) before the page is resolved.
+  const hashRoute = location.hash.match(/^#\/([A-Za-z0-9_-]+)(\?[^#]*)?$/);
+  if (hashRoute && pagesData.find(p => p.id === hashRoute[1])) {
+    history.replaceState(null, '', `/${hashRoute[1]}${hashRoute[2] || ''}`);
+  }
+
   // Resolve initial page from URL path or default to first page
   const pathId = location.pathname.replace(/^\//, '') || '';
   const initialPage = pathId && pagesData.find(p => p.id === pathId)
@@ -1768,6 +1790,29 @@ async function buildDashboard() {
   });
 }
 
+// Pages may carry an inline SVG mark (`icon_svg`) next to the text `icon`.
+// It is parsed as SVG and dropped if it holds scripts, foreignObject,
+// event handlers or javascript: URLs; otherwise the text icon is used.
+function safeSvgIcon(markup) {
+  if (typeof markup !== 'string' || !markup.trim().startsWith('<svg')) return null;
+  try {
+    const doc = new DOMParser().parseFromString(markup, 'image/svg+xml');
+    const svg = doc.documentElement;
+    if (!svg || svg.nodeName !== 'svg' || doc.querySelector('parsererror, script, foreignObject')) return null;
+    for (const el of [svg, ...svg.querySelectorAll('*')]) {
+      for (const a of [...el.attributes]) {
+        if (/^on/i.test(a.name) || /javascript:/i.test(a.value)) return null;
+      }
+    }
+    return document.importNode(svg, true);
+  } catch (e) { return null; }
+}
+
+function setPageIcon(span, page, fallback) {
+  const svg = safeSvgIcon(page.icon_svg);
+  if (svg) { span.textContent = ''; span.appendChild(svg); } else span.textContent = page.icon || fallback;
+}
+
 function buildSidebar(pages) {
   const sidebar = document.createElement('nav');
   sidebar.className = 'db-sidebar';
@@ -1866,7 +1911,7 @@ function buildSidebar(pages) {
       item.dataset.navId = page.id;
       const iconSpan = document.createElement('span');
       iconSpan.className = 'db-nav-icon';
-      iconSpan.textContent = page.icon || '📄';
+      setPageIcon(iconSpan, page, '📄');
       item.appendChild(iconSpan);
       item.appendChild(document.createTextNode(' ' + page.title));
       item.addEventListener('click', () => selectPage(page.id));
@@ -1888,7 +1933,7 @@ function buildSidebar(pages) {
       btn.className = 'db-nav-item';
       const iconSpan = document.createElement('span');
       iconSpan.className = 'db-nav-icon';
-      iconSpan.textContent = page.icon || '⚙';
+      setPageIcon(iconSpan, page, '⚙');
       btn.appendChild(iconSpan);
       btn.appendChild(document.createTextNode(' ' + page.title));
       btn.addEventListener('click', () => {
@@ -1950,14 +1995,18 @@ async function selectPage(pageId) {
     return;
   }
 
+  // Full-bleed pages (e.g. chat) fill the main column and carry their own chrome
+  const fullBleed = page.layout === 'full-bleed';
+  main.classList.toggle('db-fill', fullBleed);
+
   // Set page header (controlled by dashboard config protocol)
-  const showPageHeader = main.dataset.showPageHeader !== 'false';
+  const showPageHeader = main.dataset.showPageHeader !== 'false' && !fullBleed;
   const toolbarSlotId = `page:${pageId}:toolbar`;
   const headerHtml = showPageHeader ? `
     <div class="db-page-header">
       <div style="display:flex;align-items:flex-start;justify-content:space-between;gap:12px;flex-wrap:wrap">
         <div>
-          <h1 class="db-page-title">${page.icon || ''} ${page.title}</h1>
+          <h1 class="db-page-title">${page.icon_svg ? '<span class="db-page-icon"></span>' : (page.icon || '')} ${page.title}</h1>
           ${page.description ? `<p class="db-page-desc">${page.description}</p>` : ''}
         </div>
         <div id="db-page-toolbar-slot" class="db-slot-host" data-slot="${toolbarSlotId}"></div>
@@ -1965,6 +2014,8 @@ async function selectPage(pageId) {
     </div>
   ` : '';
   main.innerHTML = `${headerHtml}<div data-page="${pageId}" id="db-page-content"></div>`;
+  const pageIcon = main.querySelector('.db-page-icon');
+  if (pageIcon) setPageIcon(pageIcon, page, '');
   if (showPageHeader) {
     const toolbarHost = document.getElementById('db-page-toolbar-slot');
     if (toolbarHost && SLOT_REGISTRY[toolbarSlotId]) {

src/praisonaiui/templates/frontend/plugins/jobs.js

@@ -164,6 +164,20 @@ function renderProgressBar(percentage) {
   `;
 }
 
+function escapeAttr(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// Navigate to Chat and load the job's linked session (same event the
+// session-search palette and run recorder use).
+function openJobSession(sessionId) {
+  if (!sessionId) return;
+  const nav = (typeof window.aiui?.selectPage === 'function') ? window.aiui.selectPage('chat') : null;
+  Promise.resolve(nav).finally(() => {
+    window.dispatchEvent(new CustomEvent('aiui:session-select', { detail: { sessionId } }));
+  });
+}
+
 function renderJobRow(job) {
   const status = job.status || 'queued';
   const isTerminal = ['succeeded', 'failed', 'cancelled'].includes(status);
@@ -199,6 +213,7 @@ function renderJobRow(job) {
         ` : `
           ${_jobsCfg.backend !== 'praisonai' ? `<button class="aiui-btn aiui-btn-sm aiui-btn-delete" onclick="window.aiuiDeleteJob('${job.id}')" title="Delete">🗑️</button>` : ''}
         `}
+        ${job.session_id ? `<button class="aiui-btn aiui-btn-sm aiui-btn-open-session" data-session-id="${escapeAttr(job.session_id)}" onclick="window.aiuiOpenJobSession(this.dataset.sessionId)" title="Open session in Chat">💬</button>` : ''}
         <button class="aiui-btn aiui-btn-sm aiui-btn-view" onclick="window.aiuiViewJob('${job.id}')" title="View Details">
           👁️
         </button>
@@ -599,6 +614,7 @@ function checkForJobsPage(root) {
 window.aiuiCancelJob = cancelJob;
 window.aiuiDeleteJob = deleteJob;
 window.aiuiViewJob = viewJob;
+window.aiuiOpenJobSession = openJobSession;
 
 export default {
   name: 'jobs',

src/praisonaiui/templates/frontend/plugins/views/approvals.js

@@ -1,65 +1,154 @@
 /**
  * Approvals View — execution approval queue
  * API: /api/approvals
+ *
+ * Pending items render as an Approval Card (human-in-the-loop): risk, question,
+ * optional preset options / custom answer / confidence copy — surfaced only when
+ * the API supplies them, so the card stays a plain approve/deny prompt otherwise.
  */
-import { isSkillApproval } from '/plugins/views/_helpers.js';
+import { isSkillApproval, esc, emptyState } from '/plugins/views/_helpers.js';
+
+const RISK = {
+  low: { icon: '✅', color: '#22c55e' },
+  medium: { icon: '⚠️', color: '#eab308' },
+  high: { icon: '🟠', color: '#f97316' },
+  critical: { icon: '🔴', color: '#ef4444' },
+};
+
+/**
+ * Normalise a raw /api/approvals item into an ApprovalPromptModel-shaped object.
+ * Keeps the field-mapping in one place; only carries what the API actually sends.
+ */
+function toApprovalModel(a) {
+  const id = a.id || a.approval_id || '';
+  const risk = String(a.risk_level || '').toLowerCase();
+  const options = Array.isArray(a.options)
+    ? a.options.map(o => (typeof o === 'string' ? { value: o, label: o } : { value: o.value ?? o.id ?? o.label, label: o.label ?? String(o.value ?? o.id) }))
+    : [];
+  const confidence = typeof a.confidence === 'number' ? Math.round(a.confidence * (a.confidence <= 1 ? 100 : 1)) : null;
+  return {
+    id,
+    title: a.tool_name || a.action || 'Unknown',
+    question: a.reason || a.description || a.question || '',
+    agent: a.agent_name || '',
+    risk,
+    riskMeta: RISK[risk] || { icon: '❓', color: 'var(--db-text-dim)' },
+    createdAt: a.created_at ? new Date(a.created_at * 1000).toLocaleString() : '',
+    options,
+    allowCustom: a.allow_custom_answer === true || (options.length === 0 && a.custom_answer !== false && !!a.question),
+    confidence,
+    isSkill: isSkillApproval(a),
+  };
+}
+
+function approvalCard(m) {
+  const optionsHtml = m.options.length
+    ? `<div class="db-approval-options" role="radiogroup" aria-label="Response options" style="display:flex;flex-wrap:wrap;gap:6px;margin-top:10px">
+        ${m.options.map((o, i) => `
+          <label style="display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:4px 10px;border:1px solid var(--db-border);border-radius:6px;cursor:pointer">
+            <input type="radio" name="opt-${esc(m.id)}" value="${esc(o.value)}" ${i === 0 ? 'checked' : ''}> ${esc(o.label)}
+          </label>`).join('')}
+      </div>`
+    : '';
+  const customHtml = m.allowCustom
+    ? `<input class="approv-custom" data-id="${esc(m.id)}" type="text" placeholder="Custom answer (optional)"
+        aria-label="Custom answer for ${esc(m.title)}"
+        style="margin-top:10px;width:100%;padding:6px 10px;font-size:12px;background:var(--db-bg);color:var(--db-text);border:1px solid var(--db-border);border-radius:6px">`
+    : '';
+  const confidenceHtml = m.confidence != null
+    ? `<div style="font-size:11px;color:var(--db-text-dim);margin-top:6px">Model confidence: ${m.confidence}%</div>`
+    : '';
+  const skillHtml = m.isSkill
+    ? `<a href="/skills?tab=pending&approval_id=${encodeURIComponent(m.id)}" data-skill-studio="1" style="display:inline-block;margin-top:8px;font-size:11px;color:var(--db-accent);text-decoration:none">Skill write? Open Skills Studio →</a>`
+    : '';
+
+  return `
+    <div class="db-card db-approval-card" data-id="${esc(m.id)}" role="group"
+         aria-label="Approval request: ${esc(m.title)}"
+         style="margin-bottom:12px;padding:16px 20px;border-left:3px solid ${m.riskMeta.color}">
+      <div style="display:flex;align-items:flex-start;justify-content:space-between;gap:12px">
+        <div style="flex:1;min-width:0">
+          <div style="font-weight:600;font-size:14px">${m.riskMeta.icon} ${esc(m.title)}</div>
+          ${m.question ? `<div style="font-size:13px;color:var(--db-text);margin-top:6px">${esc(m.question)}</div>` : ''}
+          <div style="font-size:12px;color:var(--db-text-dim);margin-top:4px">Agent: ${esc(m.agent) || '—'}${m.risk ? ` · risk: ${esc(m.risk)}` : ''}</div>
+          ${m.createdAt ? `<div style="font-size:11px;color:var(--db-text-dim)">${esc(m.createdAt)}</div>` : ''}
+          ${optionsHtml}
+          ${customHtml}
+          ${confidenceHtml}
+          ${skillHtml}
+        </div>
+        <div style="display:flex;gap:8px;flex-shrink:0">
+          <button class="approv-yes" data-id="${esc(m.id)}" aria-label="Approve ${esc(m.title)}"
+            style="padding:6px 16px;background:rgba(34,197,94,0.15);color:#22c55e;border:1px solid rgba(34,197,94,0.3);border-radius:6px;cursor:pointer;font-size:12px">✓ Approve</button>
+          <button class="approv-no" data-id="${esc(m.id)}" aria-label="Deny ${esc(m.title)}"
+            style="padding:6px 16px;background:rgba(239,68,68,0.15);color:#ef4444;border:1px solid rgba(239,68,68,0.3);border-radius:6px;cursor:pointer;font-size:12px">✗ Deny</button>
+        </div>
+      </div>
+    </div>`;
+}
 
 export async function render(container) {
   container.innerHTML = '<div class="db-loading"><div class="db-spinner"></div></div>';
 
   let pending = [], history = [], policies = {};
   try { const r = await fetch('/api/approvals/pending'); pending = (await r.json()).approvals || []; } catch(e) {}
-  try { const r = await fetch('/api/approvals/history'); history = (await r.json()).approvals || (await r.json()).history || []; } catch(e) {}
+  try { const r = await fetch('/api/approvals/history'); const d = await r.json(); history = d.approvals || d.history || []; } catch(e) {}
   try { const r = await fetch('/api/approvals/policies'); policies = await r.json(); } catch(e) {}
 
-  const riskIcons = { low: '✅', medium: '⚠️', high: '🟠', critical: '🔴' };
+  const models = pending.map(toApprovalModel);
 
   container.innerHTML = `
     <div class="db-columns" style="grid-template-columns:repeat(3,1fr);margin-bottom:24px">
-      <div class="db-card"><div class="db-card-title">Pending</div><div class="db-card-value" style="color:#eab308">${pending.length}</div></div>
-      <div class="db-card"><div class="db-card-title">Risk Threshold</div><div class="db-card-value" style="font-size:18px">${policies.risk_threshold || 'high'}</div></div>
+      <div class="db-card"><div class="db-card-title">Pending</div><div class="db-card-value" style="color:#eab308">${models.length}</div></div>
+      <div class="db-card"><div class="db-card-title">Risk Threshold</div><div class="db-card-value" style="font-size:18px">${esc(policies.risk_threshold || 'high')}</div></div>
       <div class="db-card"><div class="db-card-title">Auto-Approve Tools</div><div class="db-card-value" style="font-size:18px">${(policies.auto_approve_tools || []).length}</div></div>
     </div>
 
     <h3 style="margin:0 0 12px;font-size:15px;font-weight:600">Pending Approvals</h3>
     <div id="approv-pending" style="margin-bottom:28px">
-      ${pending.length === 0 ? '<div class="db-viewer"><pre>No pending approvals</pre></div>' : ''}
+      ${models.length === 0 ? emptyState({ icon: '✅', title: 'No pending approvals', body: 'All clear — nothing needs your decision.' }) : models.map(approvalCard).join('')}
     </div>
 
     <h3 style="margin:0 0 12px;font-size:15px;font-weight:600">Recent History</h3>
     <div id="approv-history"></div>
   `;
 
-  const pendingEl = container.querySelector('#approv-pending');
-  pending.forEach(a => {
-    const card = document.createElement('div');
-    card.className = 'db-card';
-    card.style.cssText = 'margin-bottom:10px;padding:16px 20px;display:flex;align-items:center;justify-content:space-between';
-    const isSkill = isSkillApproval(a);
-    card.innerHTML = `
-      <div style="flex:1">
-        <div style="font-weight:500;font-size:14px">${riskIcons[a.risk_level] || '❓'} ${a.tool_name || a.action || 'Unknown'}</div>
-        <div style="font-size:12px;color:var(--db-text-dim);margin-top:4px">Agent: ${a.agent_name || '—'} · ${a.reason || ''}</div>
-        <div style="font-size:11px;color:var(--db-text-dim)">${a.created_at ? new Date(a.created_at * 1000).toLocaleString() : ''}</div>
-        ${isSkill ? `<a href="/skills?tab=pending&approval_id=${encodeURIComponent(a.id || a.approval_id || '')}" data-skill-studio="1" style="font-size:11px;color:var(--db-accent);text-decoration:none">Skill write? Open Skills Studio →</a>` : ''}
-      </div>
-      <div style="display:flex;gap:8px">
-        <button class="approv-yes" data-id="${a.id || a.approval_id}" style="padding:6px 16px;background:rgba(34,197,94,0.15);color:#22c55e;border:1px solid rgba(34,197,94,0.3);border-radius:6px;cursor:pointer;font-size:12px">✓ Approve</button>
-        <button class="approv-no" data-id="${a.id || a.approval_id}" style="padding:6px 16px;background:rgba(239,68,68,0.15);color:#ef4444;border:1px solid rgba(239,68,68,0.3);border-radius:6px;cursor:pointer;font-size:12px">✗ Deny</button>
-      </div>
-    `;
-    pendingEl.appendChild(card);
-  });
+  function collectExtra(id) {
+    const card = container.querySelector(`.db-approval-card[data-id="${CSS.escape(id)}"]`);
+    const body = {};
+    if (!card) return body;
+    const opt = card.querySelector(`input[name="opt-${CSS.escape(id)}"]:checked`);
+    if (opt) body.option = opt.value;
+    const custom = card.querySelector('.approv-custom');
+    if (custom && custom.value.trim()) body.custom_answer = custom.value.trim();
+    // Also surface the human's choice as `reason` — the only extra field the
+    // approve/deny endpoints persist today — so the answer isn't dropped while
+    // `option`/`custom_answer` stay for a future richer backend.
+    const reason = body.custom_answer || body.option;
+    if (reason != null && reason !== '') body.reason = String(reason);
+    return body;
+  }
 
-  container.querySelectorAll('.approv-yes').forEach(b => b.addEventListener('click', async () => { try { await fetch(`/api/approvals/${b.dataset.id}/approve`, {method:'POST'}); render(container); } catch(e){} }));
-  container.querySelectorAll('.approv-no').forEach(b => b.addEventListener('click', async () => { try { await fetch(`/api/approvals/${b.dataset.id}/deny`, {method:'POST'}); render(container); } catch(e){} }));
+  async function decide(id, action) {
+    try {
+      await fetch(`/api/approvals/${encodeURIComponent(id)}/${action}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(collectExtra(id)),
+      });
+      render(container);
+    } catch(e) {}
+  }
+
+  container.querySelectorAll('.approv-yes').forEach(b => b.addEventListener('click', () => decide(b.dataset.id, 'approve')));
+  container.querySelectorAll('.approv-no').forEach(b => b.addEventListener('click', () => decide(b.dataset.id, 'deny')));
 
   const historyEl = container.querySelector('#approv-history');
   (Array.isArray(history) ? history : []).slice(0, 20).forEach(h => {
     const div = document.createElement('div');
     div.style.cssText = 'padding:8px 0;border-bottom:1px solid var(--db-border);font-size:13px;display:flex;justify-content:space-between';
     const approved = h.status === 'approved' || h.approved;
-    div.innerHTML = `<span>${h.tool_name || h.action || '?'} — ${h.agent_name || ''}</span><span style="color:${approved ? '#22c55e' : '#ef4444'}">${approved ? '✓ approved' : '✗ denied'}</span>`;
+    div.innerHTML = `<span>${esc(h.tool_name || h.action || '?')} — ${esc(h.agent_name || '')}</span><span style="color:${approved ? '#22c55e' : '#ef4444'}">${approved ? '✓ approved' : '✗ denied'}</span>`;
     historyEl.appendChild(div);
   });
   if (!history.length) historyEl.innerHTML = '<div style="font-size:13px;color:var(--db-text-dim)">No history</div>';

src/praisonaiui/templates/frontend/plugins/views/chat-canvas.js

@@ -21,6 +21,7 @@ function injectStyles() {
       overflow: hidden;
     }
     .db-clean .chat-canvas-root { height: 100vh; }
+    .db-fill .chat-canvas-root { flex: 1; min-height: 0; height: auto; }
     .chat-canvas-chat {
       flex: 1 1 60%;
       min-width: 0;

src/praisonaiui/templates/frontend/plugins/views/chat.js

@@ -19,6 +19,7 @@ let isStreaming = false;
 let streamingSessionId = null;  // tracks which session is actively streaming
 let currentRunId = null;
 let agents = [];
+let allSessions = [];  // last fetched session list, filtered client-side by the rail search
 let messageQueue = [];
 let focusMode = false;
 let sessionSelectHandler = null;
@@ -221,6 +222,11 @@ function injectStyles() {
   style.textContent = `
     .chat-root { display:flex; height:calc(100vh - 140px); gap:0; border-radius:12px; overflow:hidden; border:1px solid var(--db-border); background:var(--db-card-bg); }
     .db-clean .chat-root { height:100%; border-radius:0; border:none; }
+    .db-fill .chat-root { flex:1; min-height:0; height:auto; }
+    @media (max-width:900px) {
+      .db-fill .chat-root { flex-direction:column; }
+      .db-fill .chat-sidebar-panel { width:100%; min-width:0; max-height:40vh; border-right:none; border-bottom:1px solid var(--db-border); }
+    }
     .chat-root.focus-mode .chat-sidebar-panel { display:none; }
     .chat-root.focus-mode .chat-main-panel { border-left:none; }
 
@@ -230,12 +236,17 @@ function injectStyles() {
     .chat-sidebar-agent { padding:10px 16px; border-bottom:1px solid var(--db-border); }
     .chat-sidebar-agent label { font-size:11px; color:var(--db-text-dim); display:block; margin-bottom:4px; text-transform:uppercase; font-weight:600; letter-spacing:.5px; }
     .chat-sidebar-agent select { width:100%; padding:6px 10px; background:var(--db-card-bg); border:1px solid var(--db-border); border-radius:6px; color:var(--db-text); font-size:13px; }
+    .chat-sess-search { padding:8px 16px 0; }
+    .chat-sess-search input { width:100%; box-sizing:border-box; padding:6px 10px; background:var(--db-card-bg); border:1px solid var(--db-border); border-radius:6px; color:var(--db-text); font-size:13px; }
     .chat-sess-list { flex:1; overflow-y:auto; padding:8px; }
     .chat-sess-item { padding:10px 12px; border-radius:8px; cursor:pointer; margin-bottom:4px; font-size:13px; transition:background .15s; display:flex; flex-direction:column; gap:2px; }
     .chat-sess-item:hover { background:rgba(var(--db-accent-rgb,100,100,255),.08); }
     .chat-sess-item.active { background:rgba(var(--db-accent-rgb,100,100,255),.15); }
     .chat-sess-item .sess-title { font-weight:500; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
     .chat-sess-item .sess-meta { font-size:11px; color:var(--db-text-dim); }
+    .chat-sess-item { position:relative; }
+    .chat-sess-item .sess-rename { position:absolute; top:6px; right:6px; display:none; background:none; border:none; color:var(--db-text-dim); cursor:pointer; font-size:12px; padding:2px 4px; }
+    .chat-sess-item:hover .sess-rename, .chat-sess-item .sess-rename:focus { display:block; }
 
     .chat-main-panel { flex:1; display:flex; flex-direction:column; min-width:0; }
     .chat-top-bar { padding:10px 16px; border-bottom:1px solid var(--db-border); display:flex; align-items:center; justify-content:space-between; gap:10px; }
@@ -812,6 +823,9 @@ export async function render(container) {
           <label>Agent</label>
           <select id="chat-agent-selector"><option value="">Auto (default)</option></select>
         </div>
+        <div class="chat-sess-search">
+          <input type="search" id="chat-session-search" placeholder="Search sessions…" aria-label="Search sessions" autocomplete="off">
+        </div>
         <div class="chat-sess-list" id="chat-sessions-list"></div>
       </div>
       <div class="chat-main-panel">
@@ -892,6 +906,8 @@ export async function render(container) {
   const agentSelector = document.getElementById('chat-agent-selector');
   const attachBtn = document.getElementById('chat-attach-btn');
   const fileInput = document.getElementById('chat-file-input');
+  const sessionSearch = document.getElementById('chat-session-search');
+  if (sessionSearch) sessionSearch.addEventListener('input', renderSessionList);
   // Guard: if DOM elements aren't present yet (race condition), bail out
   if (!input || !sendBtn) {
     console.warn('[chat] DOM elements not ready — skipping event binding');
@@ -1039,47 +1055,92 @@ async function loadSessions() {
       resp = await fetch('/sessions');
     }
     const data = await resp.json();
-    const sessions = data.sessions || data || [];
-    const list = document.getElementById('chat-sessions-list');
-    if (!list) return;
-    list.innerHTML = '';
-    if (sessions.length === 0) {
-      list.innerHTML = '<div style="padding:16px;text-align:center;color:var(--db-text-dim);font-size:12px">No sessions yet</div>';
-      return;
-    }
-    sessions.slice(0, 30).forEach((s) => {
-      const el = document.createElement('div');
-      const id = s.id || s.session_id || '';
-      el.className = 'chat-sess-item' + (id === currentSessionId ? ' active' : '');
-      // Show platform icon for channel sessions (e.g. Slack with SVG)
-      const platformName = s.platform || '';
-      const platSvg = _getPlatformSVG(platformName);
-      let title;
-      let titlePrefix = '';
-      if (platformName) {
-        const displayName = platformName.charAt(0).toUpperCase() + platformName.slice(1);
-        if (platSvg) {
-          titlePrefix = '<span class="sess-platform-icon ' + _getPlatformClass(platformName) + '">' + platSvg + '</span>';
-        }
-        title = displayName;
-      } else {
-        title = s.name || s.title || s.label || id.substring(0, 12) + '…';
-      }
-      const agent = s.agent_id || s.agent || '';
-      const time = timeAgo(s.created_at || s.updated_at);
-      el.innerHTML = `
-        <div class="sess-title">${titlePrefix}${escapeHtml(title)}</div>
-        <div class="sess-meta">${agent ? '🤖 ' + escapeHtml(agent) + ' · ' : ''}${time}</div>
-      `;
-      el.title = id;
-      el.addEventListener('click', () => loadSession(id));
-      list.appendChild(el);
-    });
+    const fetched = data.sessions || data || [];
+    allSessions = Array.isArray(fetched) ? fetched : [];
+    renderSessionList();
   } catch (e) {
     console.warn('[Chat] Failed to load sessions:', e);
   }
 }
 
+function _sessionMatches(s, q) {
+  const fields = [s.id, s.session_id, s.name, s.title, s.label, s.agent_id, s.agent, s.platform];
+  return fields.some((v) => typeof v === 'string' && v.toLowerCase().includes(q));
+}
+
+function renderSessionList() {
+  const list = document.getElementById('chat-sessions-list');
+  if (!list) return;
+  const input = document.getElementById('chat-session-search');
+  const q = (input && input.value || '').trim().toLowerCase();
+  const sessions = q ? allSessions.filter((s) => _sessionMatches(s, q)) : allSessions;
+  list.innerHTML = '';
+  if (sessions.length === 0) {
+    const msg = q ? 'No matching sessions' : 'No sessions yet';
+    list.innerHTML = '<div style="padding:16px;text-align:center;color:var(--db-text-dim);font-size:12px">' + msg + '</div>';
+    return;
+  }
+  sessions.slice(0, 30).forEach((s) => {
+    const el = document.createElement('div');
+    const id = s.id || s.session_id || '';
+    el.className = 'chat-sess-item' + (id === currentSessionId ? ' active' : '');
+    // Show platform icon for channel sessions (e.g. Slack with SVG)
+    const platformName = s.platform || '';
+    const platSvg = _getPlatformSVG(platformName);
+    let title;
+    let titlePrefix = '';
+    if (platformName) {
+      const displayName = platformName.charAt(0).toUpperCase() + platformName.slice(1);
+      if (platSvg) {
+        titlePrefix = '<span class="sess-platform-icon ' + _getPlatformClass(platformName) + '">' + platSvg + '</span>';
+      }
+      title = displayName;
+    } else {
+      title = s.name || s.title || s.label || id.substring(0, 12) + '…';
+    }
+    const agent = s.agent_id || s.agent || '';
+    const time = timeAgo(s.created_at || s.updated_at);
+    el.innerHTML = `
+      <div class="sess-title">${titlePrefix}${escapeHtml(title)}</div>
+      <div class="sess-meta">${agent ? '🤖 ' + escapeHtml(agent) + ' · ' : ''}${time}</div>
+    `;
+    el.title = id;
+    el.addEventListener('click', () => loadSession(id));
+    if (!platformName && id) {
+      const btn = document.createElement('button');
+      btn.className = 'sess-rename';
+      btn.title = 'Rename session';
+      btn.setAttribute('aria-label', 'Rename session');
+      btn.textContent = '✎';
+      btn.addEventListener('click', (e) => { e.stopPropagation(); renameSession(id, title); });
+      el.appendChild(btn);
+    }
+    list.appendChild(el);
+  });
+}
+
+async function renameSession(sessionId, currentTitle) {
+  const next = (window.prompt('Rename session', currentTitle || '') || '').trim();
+  if (!next || next === currentTitle) return;
+  try {
+    const resp = await fetch('/sessions/' + encodeURIComponent(sessionId), {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: next }),
+    });
+    if (!resp.ok) throw new Error('HTTP ' + resp.status);
+    const s = allSessions.find((x) => (x.id || x.session_id) === sessionId);
+    if (s) { s.title = next; delete s.name; }
+    renderSessionList();
+    if (sessionId === currentSessionId) {
+      const header = document.getElementById('chat-header-title');
+      if (header) header.textContent = next;
+    }
+  } catch (e) {
+    console.warn('[Chat] Failed to rename session:', e);
+  }
+}
+
 async function loadSession(sessionId) {
   currentSessionId = sessionId;
   refreshStreamingUI();
@@ -1131,7 +1192,8 @@ async function loadSession(sessionId) {
         title.textContent = (sessionIcon || '📨') + ' ' + displayName;
       }
     } else if (title) {
-      title.textContent = 'Session ' + sessionId.substring(0, 8);
+      const cached = allSessions.find((x) => (x.id || x.session_id) === sessionId);
+      title.textContent = (cached && (cached.name || cached.title)) || ('Session ' + sessionId.substring(0, 8));
     }
   } catch (e) {
     console.warn('[Chat] Failed to load session:', e);

tests/browser/test_replay_browser.py

@@ -0,0 +1,524 @@
+"""Browser smoke + axe accessibility check for the Replay view (dev-only, never shipped).
+
+Opt-in:  RUN_BROWSER_TESTS=1 AXE_CORE_JS=/path/to/axe.min.js pytest tests/browser -o addopts=""
+
+* Needs the ``playwright`` Python package and a Chrome install (``channel="chrome"``)
+  or a Playwright Chromium (``python -m playwright install chromium``).
+* axe-core (MPL-2.0) is loaded from ``AXE_CORE_JS`` (e.g. ``npm i axe-core`` in
+  any scratch dir); the axe checks are skipped when it is not provided.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import socket
+import threading
+import time
+from pathlib import Path
+
+import pytest
+
+if os.environ.get("RUN_BROWSER_TESTS") != "1":
+    pytest.skip("browser tests are opt-in (RUN_BROWSER_TESTS=1)", allow_module_level=True)
+
+sync_api = pytest.importorskip("playwright.sync_api")
+
+ROOT = Path(__file__).resolve().parents[2]
+FIXTURES = ROOT / "tests" / "fixtures" / "replay"
+AXE = os.environ.get("AXE_CORE_JS")
+WCAG_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"]
+
+
+def _events(name: str) -> list[dict]:
+    return [json.loads(line) for line in (FIXTURES / f"{name}.jsonl").read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+@pytest.fixture(scope="module")
+def browser():
+    with sync_api.sync_playwright() as p:
+        try:
+            b = p.chromium.launch(channel="chrome")
+        except Exception:
+            try:
+                b = p.chromium.launch()
+            except Exception as exc:  # no browser available
+                pytest.skip(f"no Chromium/Chrome available: {exc}")
+        yield b
+        b.close()
+
+
+def _page(browser, scheme: str = "light", reduced: bool = False):
+    page = browser.new_page(
+        viewport={"width": 1366, "height": 1000},
+        color_scheme=scheme,
+        reduced_motion="reduce" if reduced else "no-preference",
+    )
+    errors: list[str] = []
+    page.on("pageerror", lambda e: errors.append(str(e)))
+    page.on("console", lambda m: errors.append(m.text) if m.type == "error" else None)
+    return page, errors
+
+
+def _axe(page, selector: str = ".rp-root") -> list[dict]:
+    if not AXE:
+        return []
+    page.add_script_tag(path=AXE)
+    result = page.evaluate(
+        """async ([sel, tags]) => {
+            const r = await axe.run(document.querySelector(sel), {runOnly: {type: 'tag', values: tags}});
+            return r.violations.map(v => ({id: v.id, impact: v.impact, help: v.help, nodes: v.nodes.slice(0, 3).map(n => n.target.join(' '))}));
+        }""",
+        [selector, WCAG_TAGS],
+    )
+    return result
+
+
+def _standalone(tmp_path: Path, name: str) -> str:
+    from praisonaiui.features.replay import standalone_html
+
+    out = tmp_path / f"{name}.html"
+    out.write_text(standalone_html(_events(name), title=name), encoding="utf-8")
+    return out.as_uri()
+
+
+def _current_index(page) -> int:
+    return int(page.get_attribute('.rp-step[aria-current="step"]', "data-i"))
+
+
+@pytest.mark.parametrize("name", ["team_handoff", "flow_parallel_loop", "legacy_v10", "team_outside"])
+def test_standalone_steps_with_arrow_keys(browser, tmp_path, name):
+    page, errors = _page(browser)
+    page.goto(_standalone(tmp_path, name))
+    page.wait_for_selector(".rp-step")
+    total = page.locator(".rp-step").count()
+    assert total > 5
+    assert _current_index(page) == total - 1  # opens at the end (whole run visible)
+
+    page.locator(".rp-step").nth(total - 1).focus()
+    page.keyboard.press("Home")
+    assert _current_index(page) == 0
+    for _ in range(3):
+        page.keyboard.press("ArrowRight")
+    assert _current_index(page) == 3
+    page.keyboard.press("ArrowLeft")
+    assert _current_index(page) == 2
+    # focus follows the cursor in the step list, the scrubber and the drawer agree
+    assert page.evaluate("document.activeElement.getAttribute('data-i')") == "2"
+    assert page.input_value("#rp-scrub-range") == "2"
+    step_text = page.locator('.rp-step[aria-current="step"] .rp-step-text').inner_text()
+    assert page.locator(".rp-drawer h3").inner_text() == step_text
+    # replay: later blocks are drawn as "not reached yet"
+    assert page.locator(".rp-block.rp-future").count() > 0
+    page.keyboard.press("End")
+    assert _current_index(page) == total - 1
+    assert page.locator(".rp-block.rp-future").count() == 0
+    assert not errors, errors
+
+
+def test_standalone_drawer_tabs_map_and_axe(browser, tmp_path):
+    page, errors = _page(browser)
+    page.goto(_standalone(tmp_path, "team_handoff"))
+    page.wait_for_selector(".rp-step")
+    # select the hand-off step and read the Why tab
+    page.locator(".rp-step", has_text="handed off to Writer").click()
+    page.locator('[role="tab"]', has_text="Why").click()
+    why = page.locator("#rp-tabpanel").inner_text()
+    assert "Hand-off reason" in why and "Facts gathered" in why
+    # keyboard on the tablist moves between tabs
+    page.keyboard.press("ArrowRight")
+    assert page.get_attribute('[role="tab"][aria-selected="true"]', "id") == "rp-tab-raw"
+    assert '"event_type": "agent_handoff"' in page.locator("#rp-tabpanel pre").inner_text()
+    # manager's task snapshot shows up for the delegated task
+    page.locator(".rp-step", has_text="Task 'research' went to Researcher").click()
+    page.locator('[role="tab"]', has_text="Why").click()
+    assert "Manager's task snapshot" in page.locator("#rp-tabpanel").inner_text()
+    # approval evidence
+    page.locator(".rp-step", has_text="You approved write_file").click()
+    assert "Decided by" in page.locator("#rp-tabpanel").inner_text()
+
+    violations = _axe(page)
+    assert violations == [], json.dumps(violations, indent=2)
+
+    page.click("[data-key='overlay']")
+    page.click("[data-key='view:map']")
+    page.wait_for_selector(".rp-node")
+    assert page.locator(".rp-node").count() == 10
+    labels = page.eval_on_selector_all(".rp-edge text", "els => els.map(e => e.textContent)")
+    assert "hands off" in labels and any(t.startswith("delegates") for t in labels)
+    page.locator(".rp-node").first.focus()
+    page.keyboard.press("ArrowDown")
+    page.keyboard.press("Enter")
+    assert page.locator(".rp-drawer h3").inner_text()
+    violations = _axe(page)
+    assert violations == [], json.dumps(violations, indent=2)
+
+    page.select_option("[data-key='theme']", "dark")
+    assert page.get_attribute(".rp-root", "data-theme") == "dark"
+    violations = _axe(page)
+    assert violations == [], json.dumps(violations, indent=2)
+    page.click("[data-key='view:timeline']")
+    violations = _axe(page)
+    assert violations == [], json.dumps(violations, indent=2)
+    assert not errors, errors
+
+
+def test_reduced_motion_has_no_animation(browser, tmp_path):
+    page, _ = _page(browser, reduced=True)
+    page.goto(_standalone(tmp_path, "flow_parallel_loop"))
+    page.wait_for_selector(".rp-step")
+    names = page.evaluate(
+        "[...document.querySelectorAll('.rp-root *')].map(e => getComputedStyle(e).animationName).filter(n => n && n !== 'none')"
+    )
+    assert names == []
+
+
+def _boxes(page, selector: str) -> list[dict]:
+    return page.eval_on_selector_all(
+        selector,
+        "els => els.map(e => { const r = e.getBoundingClientRect(); return {x: r.x, y: r.y, w: r.width, h: r.height, id: e.closest('[data-block]')?.getAttribute('data-block')}; })",
+    )
+
+
+@pytest.mark.parametrize("name", ["team_outside", "team_handoff", "flow_parallel_loop"])
+def test_timeline_blocks_never_overlap(browser, tmp_path, name):
+    """An LLM span encloses its tool calls in real runs; tools go on their own row."""
+    page, errors = _page(browser)
+    page.goto(_standalone(tmp_path, name))
+    page.wait_for_selector(".rp-block")
+    boxes = _boxes(page, ".rp-block .rp-body")
+    for i, a in enumerate(boxes):
+        for b in boxes[i + 1:]:
+            apart = a["x"] + a["w"] <= b["x"] + 0.5 or b["x"] + b["w"] <= a["x"] + 0.5 or a["y"] + a["h"] <= b["y"] + 0.5 or b["y"] + b["h"] <= a["y"] + 0.5
+            assert apart, f"{a['id']} overlaps {b['id']}"
+    # a label that does not fit is ellipsized, and the full text is in the title and name
+    llm = page.locator(".rp-block.rp-k-llm").first
+    name_attr = llm.get_attribute("aria-label")
+    title = llm.locator("title").text_content()
+    assert name_attr.startswith(title)
+    llm.focus()
+    assert page.locator(".rp-tip").get_attribute("visibility") == "visible"
+    assert page.locator(".rp-tip text").text_content() == title
+    assert not errors, errors
+
+
+def test_why_tab_by_role_and_keyboard(browser, tmp_path):
+    page, errors = _page(browser)
+    page.goto(_standalone(tmp_path, "team_outside"))
+    page.wait_for_selector(".rp-step")
+    page.locator(".rp-step", has_text="Triage handed off to Billing").click()
+    page.get_by_role("tab", name="Why").click()
+    assert page.get_by_role("tab", name="Why").get_attribute("aria-selected") == "true"
+    why = page.get_by_role("tabpanel").inner_text()
+    assert "Hand-off reason" in why and "Billing question" in why and "Context passed" in why
+    # the task input
+    page.locator(".rp-step", has_text="Task 'research' went to Researcher").click()
+    assert "Task description" in page.get_by_role("tabpanel").inner_text()
+    assert "Get one fact about electric vehicles" in page.get_by_role("tabpanel").inner_text()
+    # keyboard: focus the selected tab, arrow keys move between tabs
+    page.get_by_role("tab", name="Why").focus()
+    page.keyboard.press("ArrowLeft")
+    assert page.get_by_role("tab", name="What happened").get_attribute("aria-selected") == "true"
+    page.keyboard.press("ArrowRight")
+    assert page.get_by_role("tab", name="Why").get_attribute("aria-selected") == "true"
+    assert page.evaluate("document.activeElement.getAttribute('role')") == "tab"
+    # route chosen and approval decision
+    page.goto(_standalone(tmp_path, "flow_parallel_loop"))
+    page.wait_for_selector(".rp-step")
+    page.locator(".rp-step", has_text="chose route 'publish'").click()
+    page.get_by_role("tab", name="Why").click()
+    assert "Route chosen" in page.get_by_role("tabpanel").inner_text()
+    page.goto(_standalone(tmp_path, "team_handoff"))
+    page.wait_for_selector(".rp-step")
+    page.locator(".rp-step", has_text="You approved write_file").click()
+    page.get_by_role("tab", name="Why").click()
+    panel = page.get_by_role("tabpanel").inner_text()
+    assert "Decision" in panel and "Approved with edited arguments" in panel
+    assert not errors, errors
+
+
+def test_theme_follows_system_with_override(browser, tmp_path):
+    url = _standalone(tmp_path, "team_handoff")
+    bg = "getComputedStyle(document.querySelector('.rp-root')).backgroundColor"
+    page, _ = _page(browser, scheme="dark")
+    page.goto(url)
+    page.wait_for_selector(".rp-step")
+    assert page.get_attribute(".rp-root", "data-theme") == "system"
+    assert page.evaluate(bg) == "rgb(22, 23, 27)"
+    page.select_option("[data-key='theme']", "light")
+    assert page.evaluate(bg) == "rgb(255, 255, 255)"
+    page.close()
+    page, _ = _page(browser, scheme="light")
+    page.goto(url)
+    page.wait_for_selector(".rp-step")
+    assert page.evaluate(bg) == "rgb(255, 255, 255)"
+
+
+def test_map_fits_on_open_and_groups_outside_agents(browser, tmp_path):
+    page, errors = _page(browser)
+    page.goto(_standalone(tmp_path, "team_outside"))
+    page.wait_for_selector(".rp-step")
+    page.get_by_role("button", name="Map").click()
+    page.wait_for_selector(".rp-node")
+    box = page.evaluate("(() => { const c = document.querySelector('.rp-canvas'); const r = c.getBoundingClientRect(); return {l: r.left, r: r.right, sw: c.scrollWidth, cw: c.clientWidth}; })()")
+    assert box["sw"] <= box["cw"] + 1, "map overflows on open"
+    for n in _boxes(page, ".rp-node .rp-card"):
+        assert box["l"] - 1 <= n["x"] and n["x"] + n["w"] <= box["r"] + 1
+    assert "Outside the team" in page.locator(".rp-group text").text_content()
+    outside = page.get_by_role("group", name="Outside the team")
+    assert outside.locator(".rp-node").count() == 3
+    labels = page.eval_on_selector_all(".rp-edge text", "els => els.map(e => e.textContent)")
+    assert "hands off" in labels
+    before = float(page.get_attribute(".rp-canvas svg", "width"))
+    page.get_by_role("button", name="Zoom in").click()
+    assert float(page.get_attribute(".rp-canvas svg", "width")) == pytest.approx(before * 1.5, abs=2)
+    page.get_by_role("button", name="Fit").click()
+    assert float(page.get_attribute(".rp-canvas svg", "width")) == pytest.approx(before, abs=2)
+    assert not errors, errors
+
+
+@pytest.mark.parametrize("name", ["team_outside", "flow_parallel_loop"])
+def test_phone_width_has_no_page_scroll(browser, tmp_path, name):
+    page, errors = _page(browser)
+    page.set_viewport_size({"width": 400, "height": 860})
+    page.goto(_standalone(tmp_path, name))
+    page.wait_for_selector(".rp-step")
+    assert page.evaluate("document.documentElement.scrollWidth") <= 400
+    r = page.evaluate("(() => { const b = document.querySelector('.rp-root').getBoundingClientRect(); return [b.left, b.right]; })()")
+    assert r[0] == pytest.approx(16, abs=1) and r[1] == pytest.approx(384, abs=1)
+    page.get_by_role("button", name="Map").click()
+    assert page.evaluate("document.documentElement.scrollWidth") <= 400
+    assert not errors, errors
+
+
+@pytest.mark.parametrize("order", ["core-first", "view-first"])
+def test_wrapper_style_export_boots(browser, tmp_path, order):
+    """The wrapper inlines both files as module scripts into #replay-root (which holds
+    a fallback table) after window.__REPLAY_DATA__; the view must replace it."""
+    views = ROOT / "src" / "praisonaiui" / "templates" / "frontend" / "plugins" / "views"
+    core = (views / "replay-core.js").read_text(encoding="utf-8").replace("</", "<\\/")
+    view = (views / "replay.js").read_text(encoding="utf-8").replace("</", "<\\/")
+    scripts = [core, view] if order == "core-first" else [view, core]
+    data = json.dumps({"run_id": "team-outside-01", "events": _events("team_outside"), "graph": None}).replace("<", "\\u003c")
+    html = (
+        "<!doctype html><html lang=en><head><meta charset=utf-8><title>PraisonAI Replay: x</title></head><body>"
+        "<div id=replay-root><table><tr><td>fallback</td></tr></table></div>"
+        f"<script id=replay-data>window.__REPLAY_DATA__ = {data};</script>"
+        + "".join(f"<script type=module>\n{js}\n</script>" for js in scripts)
+        + "</body></html>"
+    )
+    out = tmp_path / f"export-{order}.html"
+    out.write_text(html, encoding="utf-8")
+    page, errors = _page(browser)
+    page.goto(out.as_uri())
+    page.wait_for_selector(".rp-step")
+    assert page.locator("#replay-root table").count() == 0
+    assert page.locator(".rp-title").inner_text() == "team-outside-01"
+    # graph:null -> taken from workflow_start.data.graph
+    page.get_by_role("button", name="Map").click()
+    assert page.locator(".rp-node").count() == 10
+    assert page.locator(".rp-ask").count() == 0
+    assert not errors, errors
+
+
+# ── dashboard + live run + approval through the You lane ─────────────
+
+
+_PROVIDER_KEYS = ("OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY", "GROQ_API_KEY")
+
+
+def _no_provider_keys(monkeypatch) -> None:
+    """A real aiui server runs startup hooks; keep them from calling paid APIs."""
+    for key in _PROVIDER_KEYS:
+        monkeypatch.delenv(key, raising=False)
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture()
+def live_server(tmp_path, monkeypatch):
+    import uvicorn
+
+    import praisonaiui.server as server
+    from praisonaiui.features import approvals
+    from praisonaiui.features.replay import configure_replay_app
+
+    traces = tmp_path / "traces"
+    traces.mkdir()
+    for name in ("team_handoff", "flow_parallel_loop"):
+        shutil.copy(FIXTURES / f"{name}.jsonl", traces / f"{name}.jsonl")
+    lines = (FIXTURES / "team_handoff.jsonl").read_text(encoding="utf-8").splitlines(keepends=True)
+    cut = next(i for i, line in enumerate(lines) if '"approval_decided"' in line)
+    live = traces / "live-team.jsonl"
+    live.write_text("".join(lines[:cut]), encoding="utf-8")
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(traces))
+    monkeypatch.setenv("AIUI_DATA_DIR", str(tmp_path / "aiui-data"))
+    monkeypatch.setenv("PRAISONAI_HOME", str(tmp_path / "praisonai-home"))
+    _no_provider_keys(monkeypatch)
+    store = approvals.SimpleApprovalManager()
+    monkeypatch.setattr(approvals, "_approval_manager", store)
+
+    server.reset_state()
+    configure_replay_app()
+    app = server.create_app()
+    port = _free_port()
+    srv = uvicorn.Server(uvicorn.Config(app, host="127.0.0.1", port=port, log_level="warning"))
+    t = threading.Thread(target=srv.run, daemon=True)
+    t.start()
+    for _ in range(100):
+        if srv.started:
+            break
+        time.sleep(0.05)
+    yield {"url": f"http://127.0.0.1:{port}", "store": store, "live": live, "lines": lines, "cut": cut}
+    srv.should_exit = True
+    t.join(timeout=5)
+    server.reset_state()
+
+
+def test_dashboard_live_run_and_approval(browser, live_server):
+    pytest.importorskip("praisonaiagents.approval.protocols")
+    from praisonaiagents.approval.protocols import ApprovalRequest
+
+    from praisonaiui.features.approvals import _UIStoreBackend
+
+    store = live_server["store"]
+    backend = _UIStoreBackend(store, timeout=30)
+    box = {}
+    req = ApprovalRequest(tool_name="write_file", arguments={"path": "draft.md", "content": "hello"},
+                          risk_level="high", agent_name="Writer", approval_id="appr-0001")
+    t = threading.Thread(target=lambda: box.setdefault("d", backend.request_approval_sync(req)), daemon=True)
+    t.start()
+
+    page, errors = _page(browser)
+    page.goto(f"{live_server['url']}/#/replay?run=live-team")
+    page.wait_for_selector(".rp-run")
+    assert page.evaluate("location.pathname + location.search") == "/replay?run=live-team"
+    assert page.locator(".rp-run[aria-current='true']").inner_text().startswith("Solar sail brief")
+    assert page.locator(".rp-badge.rp-b-live").count() >= 1
+
+    card = page.locator(".rp-ask")
+    card.wait_for()
+    assert "Writer asks to run write_file" in card.inner_text()
+    page.get_by_role("button", name="Edit arguments…").click()
+    ta = page.locator(".rp-ask textarea")
+    ta.wait_for()
+    assert json.loads(ta.input_value()) == {"path": "draft.md", "content": "hello"}  # server-held args, not redacted
+    ta.fill("{not json")
+    assert ta.get_attribute("aria-invalid") == "true"
+    assert "Not valid JSON" in page.locator(".rp-ask .rp-err").inner_text()
+    ta.fill('{"path": "docs/draft.md", "content": "hello"}')
+    assert ta.get_attribute("aria-invalid") == "false"
+    violations = _axe(page)
+    assert violations == [], json.dumps(violations, indent=2)
+    page.get_by_role("button", name="Approve with these arguments").click()
+    t.join(timeout=10)
+    decision = box["d"]
+    assert decision.approved is True
+    assert decision.modified_args == {"path": "docs/draft.md", "content": "hello"}
+    page.locator(".rp-ask [role='status']").wait_for()
+
+    # the run continues: the rest of the file streams in over SSE
+    with open(live_server["live"], "a", encoding="utf-8") as fh:
+        fh.write("".join(live_server["lines"][live_server["cut"]:]))
+    page.wait_for_selector(".rp-step:has-text('You approved write_file')", timeout=10000)
+    page.wait_for_selector(".rp-step:has-text('Recording ended.')", timeout=10000)
+    assert page.locator(".rp-ask").count() == 0
+    page.wait_for_selector(".rp-bar .rp-b-completed", timeout=15000)
+    assert not [e for e in errors if "favicon" not in e], errors
+
+
+def test_empty_state_explains_how_to_record(browser, tmp_path, monkeypatch):
+    import uvicorn
+
+    import praisonaiui.server as server
+    from praisonaiui.features.replay import configure_replay_app
+
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(tmp_path / "empty"))
+    monkeypatch.setenv("AIUI_DATA_DIR", str(tmp_path / "aiui-data"))
+    monkeypatch.setenv("PRAISONAI_HOME", str(tmp_path / "praisonai-home"))
+    _no_provider_keys(monkeypatch)
+    server.reset_state()
+    configure_replay_app()
+    app = server.create_app()
+    port = _free_port()
+    srv = uvicorn.Server(uvicorn.Config(app, host="127.0.0.1", port=port, log_level="warning"))
+    th = threading.Thread(target=srv.run, daemon=True)
+    th.start()
+    try:
+        for _ in range(100):
+            if srv.started:
+                break
+            time.sleep(0.05)
+        page, _ = _page(browser)
+        page.goto(f"http://127.0.0.1:{port}/")
+        page.wait_for_selector(".rp-empty")
+        text = page.locator(".rp-empty").inner_text()
+        assert "praisonai replay view agents.yaml" in text
+        assert "with record(live=True):" in text
+        violations = _axe(page)
+        assert violations == [], json.dumps(violations, indent=2)
+    finally:
+        srv.should_exit = True
+        th.join(timeout=5)
+        server.reset_state()
+
+
+def test_embedded_run_box_draws_each_step_live_then_plays_back(browser, tmp_path, monkeypatch):
+    """create_replay_app(run=...) mounted in a host app: Run, watch the map, then Play."""
+    import uvicorn
+    from starlette.applications import Starlette
+    from starlette.routing import Mount
+
+    from praisonaiui.features.replay import create_replay_app
+
+    traces = tmp_path / "traces"
+    traces.mkdir()
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(traces))
+    lines = (FIXTURES / "flow_parallel_loop.jsonl").read_text(encoding="utf-8").splitlines(keepends=True)
+    seen = []
+
+    def runner(text, run_id):  # writes a recorded flow slowly, like a live run
+        seen.append(text)
+        with open(traces / f"{run_id}.jsonl", "w", encoding="utf-8") as fh:
+            for line in lines:
+                fh.write(line)
+                fh.flush()
+                time.sleep(0.08)
+
+    host = Starlette(routes=[Mount("/replay", app=create_replay_app(runner, input="weekly digest"))])
+    port = _free_port()
+    srv = uvicorn.Server(uvicorn.Config(host, host="127.0.0.1", port=port, log_level="warning"))
+    t = threading.Thread(target=srv.run, daemon=True)
+    t.start()
+    for _ in range(100):
+        if srv.started:
+            break
+        time.sleep(0.05)
+    try:
+        page, errors = _page(browser)
+        page.add_init_script("try{localStorage.setItem('rp-view','map')}catch(e){}")
+        page.goto(f"http://127.0.0.1:{port}/replay/")
+        page.wait_for_selector(".rp-empty h2:has-text('Nothing has run yet')")
+        page.get_by_role("button", name="▶ Run").click()
+        page.wait_for_selector(".rp-node.rp-st-running", timeout=10000)  # a step is drawn as running
+        assert page.locator(".rp-node.rp-unvisited").count() > 0  # later steps not reached yet
+        page.wait_for_selector(".rp-bar .rp-b-completed", timeout=20000)
+        assert seen == ["weekly digest"]
+        assert page.locator(".rp-node.rp-st-running").count() == 0
+        assert page.get_by_role("button", name="▶ Run").is_enabled()
+        page.get_by_role("button", name="▶ Play").click()  # from the end: restarts at step 1
+        page.wait_for_timeout(1300)
+        assert page.locator("[data-key=play]").inner_text() == "❚❚ Pause"
+        assert page.locator(".rp-node.rp-unvisited").count() > 0  # the map rewound with the cursor
+        page.locator("[data-key=play]").click()
+        violations = _axe(page)
+        assert violations == [], json.dumps(violations, indent=2)
+        assert not errors, errors
+    finally:
+        srv.should_exit = True
+        t.join(timeout=5)

tests/fixtures/replay/flow_parallel_loop.jsonl

@@ -0,0 +1,42 @@
+{"schema_version":"1.1","event_type":"session_start","timestamp":1767225600.0,"session_id":"sess-flow-01","agent_name":"","sequence_num":0,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01"}
+{"schema_version":"1.1","event_type":"workflow_start","timestamp":1767225600.02,"session_id":"sess-flow-01","agent_name":"","sequence_num":1,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"kind":"flow","name":"Weekly digest","process":"flow","graph":{"schema":"praisonai.graph/1","kind":"flow","name":"Weekly digest","process":"flow","nodes":[{"id":"start:begin","kind":"start","label":"Brief","parent":null,"meta":{}},{"id":"step:plan","kind":"step","label":"plan","parent":null,"meta":{"agent":"Planner"}},{"id":"step:gather","kind":"fork","label":"gather","parent":null,"meta":{"pattern":"parallel"}},{"id":"step:news","kind":"step","label":"news","parent":"step:gather","meta":{"agent":"Fetcher"}},{"id":"step:papers","kind":"step","label":"papers","parent":"step:gather","meta":{"agent":"Fetcher"}},{"id":"step:merge","kind":"join","label":"merge","parent":null,"meta":{}},{"id":"step:review_loop","kind":"step","label":"review_loop","parent":null,"meta":{"pattern":"loop"}},{"id":"step:polish","kind":"step","label":"polish","parent":"step:review_loop","meta":{"agent":"Editor"}},{"id":"step:decide","kind":"decision","label":"decide","parent":null,"meta":{"pattern":"route"}},{"id":"step:publish","kind":"step","label":"publish","parent":null,"meta":{"agent":"Publisher"}},{"id":"step:archive","kind":"step","label":"archive","parent":null,"meta":{}},{"id":"end:done","kind":"end","label":"Delivered","parent":null,"meta":{}}],"edges":[{"id":"start:begin->step:plan:next","source":"start:begin","target":"step:plan","kind":"next","label":null},{"id":"step:plan->step:gather:next","source":"step:plan","target":"step:gather","kind":"next","label":null},{"id":"step:gather->step:news:parallel","source":"step:gather","target":"step:news","kind":"parallel","label":null},{"id":"step:gather->step:papers:parallel","source":"step:gather","target":"step:papers","kind":"parallel","label":null},{"id":"step:news->step:merge:next","source":"step:news","target":"step:merge","kind":"next","label":null},{"id":"step:papers->step:merge:next","source":"step:papers","target":"step:merge","kind":"next","label":null},{"id":"step:merge->step:review_loop:next","source":"step:merge","target":"step:review_loop","kind":"next","label":null},{"id":"step:review_loop->step:polish:loop","source":"step:review_loop","target":"step:polish","kind":"loop","label":"until approved"},{"id":"step:polish->step:review_loop:loop","source":"step:polish","target":"step:review_loop","kind":"loop","label":null},{"id":"step:review_loop->step:decide:next","source":"step:review_loop","target":"step:decide","kind":"next","label":null},{"id":"step:decide->step:publish:routes","source":"step:decide","target":"step:publish","kind":"routes","label":"publish"},{"id":"step:decide->step:archive:routes","source":"step:decide","target":"step:archive","kind":"routes","label":"archive"},{"id":"step:publish->end:done:next","source":"step:publish","target":"end:done","kind":"next","label":null},{"id":"step:archive->end:done:next","source":"step:archive","target":"end:done","kind":"next","label":null}]}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":0}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225600.05,"session_id":"sess-flow-01","agent_name":"Planner","sequence_num":2,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"plan"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":1,"node_id":"step:plan"}
+{"schema_version":"1.1","event_type":"agent_start","timestamp":1767225600.06,"session_id":"sess-flow-01","agent_name":"Planner","sequence_num":3,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":2,"node_id":"agent:Planner"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225600.1,"session_id":"sess-flow-01","agent_name":"Planner","sequence_num":4,"messages_count":3,"tokens_used":150,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":3,"node_id":"agent:Planner"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225600.9,"session_id":"sess-flow-01","agent_name":"Planner","sequence_num":5,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":60,"duration_ms":800.0,"finish_reason":"stop","model":"gpt-4o-mini"},"prompt_tokens":150,"completion_tokens":60,"cost_usd":5.9e-05,"run_id":"flow-loop-01","parent_seq":3,"node_id":"agent:Planner"}
+{"schema_version":"1.1","event_type":"agent_end","timestamp":1767225600.95,"session_id":"sess-flow-01","agent_name":"Planner","sequence_num":6,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":3,"node_id":"agent:Planner"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225601.0,"session_id":"sess-flow-01","agent_name":"Planner","sequence_num":7,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":950.0,"output_preview":"Gather news and papers."},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":2,"node_id":"step:plan"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225601.05,"session_id":"sess-flow-01","agent_name":"","sequence_num":8,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"gather","pattern":"parallel"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":1,"node_id":"step:gather"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225601.1,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":9,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"news"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"branch_id":"gather/0","run_id":"flow-loop-01","parent_seq":8,"node_id":"step:news"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225601.1,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":10,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"papers"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"branch_id":"gather/1","run_id":"flow-loop-01","parent_seq":8,"node_id":"step:papers"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225601.15,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":11,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"fetch_rss","tool_args":{"url":"https://example.org/news.rss"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"branch_id":"gather/0","run_id":"flow-loop-01","parent_seq":9,"node_id":"tool:Fetcher/fetch_rss"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225601.16,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":12,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"search_papers","tool_args":{"query":"agent tracing"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"branch_id":"gather/1","run_id":"flow-loop-01","parent_seq":10,"node_id":"tool:Fetcher/search_papers"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225602.4,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":13,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"fetch_rss","result":"12 items","duration_ms":1250.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"branch_id":"gather/0","run_id":"flow-loop-01","parent_seq":11,"node_id":"tool:Fetcher/fetch_rss"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225603.0,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":14,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"search_papers","result":"5 papers","duration_ms":1840.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.001,"branch_id":"gather/1","run_id":"flow-loop-01","parent_seq":12,"node_id":"tool:Fetcher/search_papers"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225602.45,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":15,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":1350.0,"output_preview":"12 items"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"branch_id":"gather/0","run_id":"flow-loop-01","parent_seq":9,"node_id":"step:news"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225603.05,"session_id":"sess-flow-01","agent_name":"Fetcher","sequence_num":16,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":1950.0,"output_preview":"5 papers"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"branch_id":"gather/1","run_id":"flow-loop-01","parent_seq":10,"node_id":"step:papers"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225603.1,"session_id":"sess-flow-01","agent_name":"","sequence_num":17,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":2050.0},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":8,"node_id":"step:gather"}
+{"schema_version":"1.1","event_type":"context_rebalance","timestamp":1767225603.12,"session_id":"sess-flow-01","agent_name":"","sequence_num":18,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"note":"future event type"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":1,"future_field":{"x":1}}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225603.15,"session_id":"sess-flow-01","agent_name":"","sequence_num":19,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"review_loop","pattern":"loop"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":1,"node_id":"step:review_loop"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225603.2,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":20,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"polish","iteration":1},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":19,"node_id":"step:polish"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225603.22,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":21,"messages_count":3,"tokens_used":400,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":20,"node_id":"agent:Editor"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225603.92,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":22,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":90,"duration_ms":700.0,"finish_reason":"stop","model":"gpt-4o-mini"},"prompt_tokens":400,"completion_tokens":90,"cost_usd":0.000114,"run_id":"flow-loop-01","parent_seq":20,"node_id":"agent:Editor"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225603.95,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":23,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":750.0,"output_preview":"Draft v2"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":20,"node_id":"step:polish"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225604.0,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":24,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"polish","iteration":2},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":19,"node_id":"step:polish"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225604.02,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":25,"messages_count":3,"tokens_used":450,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":24,"node_id":"agent:Editor"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225604.72,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":26,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":90,"duration_ms":700.0,"finish_reason":"stop","model":"gpt-4o-mini"},"prompt_tokens":450,"completion_tokens":90,"cost_usd":0.00012150000000000001,"run_id":"flow-loop-01","parent_seq":24,"node_id":"agent:Editor"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225604.75,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":27,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":750.0,"output_preview":"Draft v3"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":24,"node_id":"step:polish"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225604.8,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":28,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"polish","iteration":3},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":19,"node_id":"step:polish"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225604.82,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":29,"messages_count":3,"tokens_used":500,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":28,"node_id":"agent:Editor"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225605.52,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":30,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":90,"duration_ms":700.0,"finish_reason":"stop","model":"gpt-4o-mini"},"prompt_tokens":500,"completion_tokens":90,"cost_usd":0.00012900000000000002,"run_id":"flow-loop-01","parent_seq":28,"node_id":"agent:Editor"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225605.55,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":31,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":750.0,"output_preview":"Draft v4"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":28,"node_id":"step:polish"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225605.6,"session_id":"sess-flow-01","agent_name":"","sequence_num":32,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":2450.0},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":19,"node_id":"step:review_loop"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225605.65,"session_id":"sess-flow-01","agent_name":"","sequence_num":33,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"decide","pattern":"route"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":1,"node_id":"step:decide"}
+{"schema_version":"1.1","event_type":"agent_handoff","timestamp":1767225605.7,"session_id":"sess-flow-01","agent_name":"Editor","sequence_num":34,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"from_agent":"Editor","to_agent":"Publisher","kind":"route","reason":"Draft approved by reviewer score 0.92","context_passed":{"score":0.92}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":33,"node_id":"step:decide"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225605.75,"session_id":"sess-flow-01","agent_name":"","sequence_num":35,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":100.0,"route":"publish"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":33,"node_id":"step:decide"}
+{"schema_version":"1.1","event_type":"step_start","timestamp":1767225605.8,"session_id":"sess-flow-01","agent_name":"Publisher","sequence_num":36,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"publish"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":1,"node_id":"step:publish"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225605.85,"session_id":"sess-flow-01","agent_name":"Publisher","sequence_num":37,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"post_to_blog","tool_args":{"title":"Weekly digest"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":36,"node_id":"tool:Publisher/post_to_blog"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225606.45,"session_id":"sess-flow-01","agent_name":"Publisher","sequence_num":38,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"post_to_blog","result":"posted /digest/42","duration_ms":600.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":37,"node_id":"tool:Publisher/post_to_blog"}
+{"schema_version":"1.1","event_type":"step_end","timestamp":1767225606.5,"session_id":"sess-flow-01","agent_name":"Publisher","sequence_num":39,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":700.0,"output_preview":"posted"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":36,"node_id":"step:publish"}
+{"schema_version":"1.1","event_type":"workflow_end","timestamp":1767225606.55,"session_id":"sess-flow-01","agent_name":"","sequence_num":40,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":6530.0},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":1}
+{"schema_version":"1.1","event_type":"session_end","timestamp":1767225606.6,"session_id":"sess-flow-01","agent_name":"","sequence_num":41,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"flow-loop-01","parent_seq":0}

tests/fixtures/replay/legacy_v10.jsonl

@@ -0,0 +1,16 @@
+{"schema_version":"1.0","event_type":"session_start","timestamp":1767225600.0,"session_id":"legacy-sess-10","agent_name":"","sequence_num":0,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}
+{"schema_version":"1.0","event_type":"agent_start","timestamp":1767225600.1,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":1,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"role":"Assistant"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}
+{"schema_version":"1.0","event_type":"message_added","timestamp":1767225600.15,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":2,"messages_count":1,"tokens_used":0,"tokens_budget":0,"data":{"role":"user","content":"What is 17 * 23?"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}
+{"schema_version":"1.0","event_type":"llm_request","timestamp":1767225600.2,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":3,"messages_count":3,"tokens_used":90,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"llm_response","timestamp":1767225600.7,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":4,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":20,"duration_ms":500.0,"finish_reason":"tool_calls","model":"gpt-4o-mini"},"prompt_tokens":90,"completion_tokens":20,"cost_usd":2.6e-05,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"tool_call_start","timestamp":1767225600.75,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":5,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"calculator","tool_args":{"expression":"17*23"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"tool_call_end","timestamp":1767225600.76,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":6,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"calculator","result":"391","duration_ms":10.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"llm_request","timestamp":1767225600.8,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":7,"messages_count":3,"tokens_used":130,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"llm_response","timestamp":1767225601.2,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":8,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":12,"duration_ms":400.0,"finish_reason":"stop","model":"gpt-4o-mini"},"prompt_tokens":130,"completion_tokens":12,"cost_usd":2.7e-05,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"agent_handoff","timestamp":1767225601.25,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":9,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"from_agent":"Assistant","to_agent":"Checker","reason":"Double-check the arithmetic","context_passed":{"answer":391}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}
+{"schema_version":"1.0","event_type":"agent_end","timestamp":1767225601.26,"session_id":"legacy-sess-10","agent_name":"Assistant","sequence_num":10,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}
+{"schema_version":"1.0","event_type":"agent_start","timestamp":1767225601.3,"session_id":"legacy-sess-10","agent_name":"Checker","sequence_num":11,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"role":"Checker"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}
+{"schema_version":"1.0","event_type":"llm_request","timestamp":1767225601.35,"session_id":"legacy-sess-10","agent_name":"Checker","sequence_num":12,"messages_count":3,"tokens_used":60,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"llm_response","timestamp":1767225601.8,"session_id":"legacy-sess-10","agent_name":"Checker","sequence_num":13,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":8,"duration_ms":450.0,"finish_reason":"stop","model":"gpt-4o-mini"},"prompt_tokens":60,"completion_tokens":8,"cost_usd":1.4e-05,"parent_seq":null,"node_id":null}
+{"schema_version":"1.0","event_type":"agent_end","timestamp":1767225601.85,"session_id":"legacy-sess-10","agent_name":"Checker","sequence_num":14,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}
+{"schema_version":"1.0","event_type":"session_end","timestamp":1767225601.9,"session_id":"legacy-sess-10","agent_name":"","sequence_num":15,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0}

tests/fixtures/replay/make_fixtures.py

@@ -0,0 +1,388 @@
+"""Regenerate the PraisonAI Replay JSONL fixtures (contract v1, schema 1.1 + 1.0).
+
+Run from the repo root::
+
+    python tests/fixtures/replay/make_fixtures.py
+
+The output is deterministic (fixed timestamps, no uuids) so the files are
+committed and the tests compare against exact values.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+T0 = 1767225600.0  # 2026-01-01T00:00:00Z
+
+
+class _Run:
+    """Tiny emitter that mimics ContextTraceEmitter's to_dict() output."""
+
+    def __init__(self, session_id: str, run_id: str | None, schema: str = "1.1") -> None:
+        self.session_id = session_id
+        self.run_id = run_id
+        self.schema = schema
+        self.seq = 0
+        self.events: list[dict] = []
+
+    def emit(self, event_type: str, t: float, agent: str = "", data: dict | None = None, **kw) -> int:
+        ev = {
+            "schema_version": self.schema,
+            "event_type": event_type,
+            "timestamp": round(T0 + t, 3),
+            "session_id": self.session_id,
+            "agent_name": agent,
+            "sequence_num": self.seq,
+            "messages_count": kw.pop("messages_count", 0),
+            "tokens_used": kw.pop("tokens_used", 0),
+            "tokens_budget": kw.pop("tokens_budget", 0),
+            "data": data or {},
+            "prompt_tokens": kw.pop("prompt_tokens", 0),
+            "completion_tokens": kw.pop("completion_tokens", 0),
+            "cost_usd": kw.pop("cost_usd", 0.0),
+        }
+        for key in ("branch_id", "content_hash"):
+            if kw.get(key) is not None:
+                ev[key] = kw.pop(key)
+            else:
+                kw.pop(key, None)
+        if self.schema != "1.0":
+            if self.run_id:
+                ev["run_id"] = self.run_id
+            for key in ("parent_seq", "node_id"):
+                if kw.get(key) is not None:
+                    ev[key] = kw.pop(key)
+                else:
+                    kw.pop(key, None)
+        ev.update(kw)  # unknown/extra fields pass straight through
+        self.events.append(ev)
+        self.seq += 1
+        return ev["sequence_num"]
+
+    def llm(self, t: float, agent: str, dur: float, parent: int | None, *, prompt: int, completion: int,
+            cost: float, model: str = "gpt-4o-mini", finish: str = "stop", content: str = "",
+            branch: str | None = None, node: str | None = None) -> None:
+        self.emit("llm_request", t, agent, {"model": model}, parent_seq=parent, messages_count=3,
+                  tokens_used=prompt, tokens_budget=128000, branch_id=branch, node_id=node)
+        data = {"response_tokens": completion, "duration_ms": round(dur * 1000, 1),
+                "finish_reason": finish, "model": model}
+        if content:
+            data["response_content"] = content
+        self.emit("llm_response", t + dur, agent, data, parent_seq=parent, prompt_tokens=prompt,
+                  completion_tokens=completion, cost_usd=cost, branch_id=branch, node_id=node)
+
+    def tool(self, t: float, agent: str, name: str, args: dict, dur: float, parent: int | None, *,
+             result: str, cost: float = 0.0, error: str | None = None, branch: str | None = None) -> None:
+        node = f"tool:{agent}/{name}" if self.schema != "1.0" else None
+        s = self.emit("tool_call_start", t, agent, {"tool_name": name, "tool_args": args},
+                      parent_seq=parent, node_id=node, branch_id=branch)
+        self.emit("tool_call_end", t + dur, agent,
+                  {"tool_name": name, "result": result, "duration_ms": round(dur * 1000, 1), "error": error},
+                  parent_seq=s if self.schema != "1.0" else None, node_id=node, cost_usd=cost, branch_id=branch)
+
+    def write(self, name: str, *, partial_tail: str | None = None) -> None:
+        path = HERE / name
+        with open(path, "w", encoding="utf-8", newline="\n") as fh:
+            for ev in self.events:
+                fh.write(json.dumps(ev, separators=(",", ":")) + "\n")
+            if partial_tail:
+                fh.write(partial_tail)
+        print(f"wrote {path.name}: {len(self.events)} events")
+
+
+def team_handoff() -> None:
+    """Hierarchical 2-agent team: Manager delegates, Researcher hands off to Writer.
+
+    Researcher calls web_search three times in a row (collapses to x3); Writer
+    asks for approval to run write_file, the human approves with edited args.
+    """
+    r = _Run("sess-team-01", "team-handoff-01")
+    graph = {
+        "schema": "praisonai.graph/1", "kind": "team", "name": "Solar sail brief", "process": "hierarchical",
+        "nodes": [
+            {"id": "start:begin", "kind": "start", "label": "Brief", "parent": None, "meta": {}},
+            {"id": "manager:Manager", "kind": "manager", "label": "Manager", "parent": None, "meta": {}},
+            {"id": "task:research", "kind": "task", "label": "research", "parent": None, "meta": {}},
+            {"id": "task:write", "kind": "task", "label": "write", "parent": None, "meta": {}},
+            {"id": "agent:Researcher", "kind": "agent", "label": "Researcher", "parent": None, "meta": {}},
+            {"id": "agent:Writer", "kind": "agent", "label": "Writer", "parent": None, "meta": {}},
+            {"id": "tool:Researcher/web_search", "kind": "tool", "label": "web_search", "parent": None, "meta": {}},
+            {"id": "tool:Writer/write_file", "kind": "tool", "label": "write_file", "parent": None, "meta": {}},
+            {"id": "human:you", "kind": "human", "label": "You", "parent": None, "meta": {}},
+            {"id": "end:done", "kind": "end", "label": "Delivered", "parent": None, "meta": {}},
+        ],
+        "edges": [
+            {"id": "start:begin->manager:Manager:next", "source": "start:begin", "target": "manager:Manager", "kind": "next", "label": None},
+            {"id": "manager:Manager->task:research:delegates", "source": "manager:Manager", "target": "task:research", "kind": "delegates", "label": None},
+            {"id": "manager:Manager->task:write:delegates", "source": "manager:Manager", "target": "task:write", "kind": "delegates", "label": None},
+            {"id": "task:write->task:research:depends_on", "source": "task:write", "target": "task:research", "kind": "depends_on", "label": None},
+            {"id": "task:research->agent:Researcher:assigned", "source": "task:research", "target": "agent:Researcher", "kind": "assigned", "label": None},
+            {"id": "task:write->agent:Writer:assigned", "source": "task:write", "target": "agent:Writer", "kind": "assigned", "label": None},
+            {"id": "agent:Researcher->agent:Writer:handoff", "source": "agent:Researcher", "target": "agent:Writer", "kind": "handoff", "label": None},
+            {"id": "agent:Researcher->tool:Researcher/web_search:uses", "source": "agent:Researcher", "target": "tool:Researcher/web_search", "kind": "uses", "label": None},
+            {"id": "agent:Writer->tool:Writer/write_file:uses", "source": "agent:Writer", "target": "tool:Writer/write_file", "kind": "uses", "label": None},
+            {"id": "human:you->tool:Writer/write_file:reviews", "source": "human:you", "target": "tool:Writer/write_file", "kind": "reviews", "label": None},
+            {"id": "agent:Writer->end:done:next", "source": "agent:Writer", "target": "end:done", "kind": "next", "label": None},
+        ],
+    }
+    s0 = r.emit("session_start", 0.0, "", {"source": "record"})
+    w = r.emit("workflow_start", 0.05, "", {"kind": "team", "name": "Solar sail brief", "process": "hierarchical",
+                                           "graph": graph}, parent_seq=s0)
+    r.emit("message_added", 0.1, "", {"role": "user", "content": "Write a short brief on solar sails."}, parent_seq=w)
+    r.llm(0.2, "Manager", 0.6, w, prompt=210, completion=48, cost=0.000060, node="manager:Manager",
+          content="Delegate research first, then writing.")
+    r.emit("agent_handoff", 0.85, "Manager", {
+        "from_agent": "Manager", "to_agent": "Researcher", "kind": "delegate",
+        "reason": "Research has to come before writing.",
+        "context_passed": {"task_snapshot": {"task": "research", "description": "Find three facts about solar sails",
+                                             "expected_output": "3 bullet facts", "status": "not started"}},
+    }, parent_seq=w, node_id="manager:Manager")
+    t1 = r.emit("task_start", 0.9, "Researcher", {"name": "research", "agent": "Researcher",
+                                                  "description_preview": "Find three facts about solar sails"},
+                parent_seq=w, node_id="task:research")
+    a1 = r.emit("agent_start", 0.95, "Researcher", {"role": "Researcher", "goal": "Find facts"},
+                parent_seq=t1, node_id="agent:Researcher")
+    r.emit("message_added", 1.0, "Researcher", {"role": "user", "content": "Find three facts about solar sails"},
+           parent_seq=a1)
+    r.llm(1.05, "Researcher", 0.9, a1, prompt=320, completion=40, cost=0.000072, finish="tool_calls",
+          node="agent:Researcher")
+    r.tool(2.0, "Researcher", "web_search", {"query": "solar sail facts"}, 1.2, a1,
+           result="IKAROS (2010) was the first interplanetary solar sail.", cost=0.002)
+    r.tool(3.25, "Researcher", "web_search", {"query": "solar sail missions"}, 1.1, a1,
+           result="LightSail 2 raised its orbit using sunlight in 2019.", cost=0.002)
+    r.tool(4.4, "Researcher", "web_search", {"query": "solar sail physics"}, 0.9, a1,
+           result="Photon pressure at 1 AU is about 9 micronewtons per square metre.", cost=0.002)
+    r.llm(5.35, "Researcher", 1.4, a1, prompt=880, completion=160, cost=0.000228, node="agent:Researcher",
+          content="1. IKAROS ... 2. LightSail 2 ... 3. ~9 uN/m^2")
+    r.emit("agent_end", 6.8, "Researcher", {"status": "completed"}, parent_seq=a1, node_id="agent:Researcher")
+    r.emit("task_end", 6.85, "Researcher", {"status": "completed", "retries": 0, "duration_ms": 5950.0,
+                                             "output_preview": "1. IKAROS ... 2. LightSail 2 ... 3. ~9 uN/m^2"},
+           parent_seq=t1, node_id="task:research")
+    r.emit("agent_handoff", 6.9, "Researcher", {
+        "from_agent": "Researcher", "to_agent": "Writer", "kind": "handoff",
+        "reason": "Facts gathered; needs drafting.",
+        "context_passed": {"facts": ["IKAROS 2010", "LightSail 2 2019", "~9 uN/m^2 at 1 AU"]},
+    }, parent_seq=w, node_id="agent:Researcher")
+    t2 = r.emit("task_start", 6.95, "Writer", {"name": "write", "agent": "Writer",
+                                               "description_preview": "Draft a 100-word brief into draft.md"},
+                parent_seq=w, node_id="task:write")
+    a2 = r.emit("agent_start", 7.0, "Writer", {"role": "Writer"}, parent_seq=t2, node_id="agent:Writer")
+    r.llm(7.05, "Writer", 1.6, a2, prompt=640, completion=220, cost=0.000228, finish="tool_calls",
+          node="agent:Writer")
+    ap = r.emit("approval_requested", 8.7, "Writer", {
+        "approval_id": "appr-0001", "tool": "write_file",
+        "args": {"path": "draft.md", "content": "[REDACTED]"}, "risk": "high", "kind": "tool_call",
+    }, parent_seq=a2, node_id="tool:Writer/write_file")
+    r.emit("approval_decided", 11.2, "", {
+        "approval_id": "appr-0001", "approved": True, "reason": "Use the docs folder.",
+        "approver": "user", "modified": True,
+    }, parent_seq=ap, node_id="tool:Writer/write_file")
+    r.tool(11.25, "Writer", "write_file", {"path": "docs/draft.md", "content": "[REDACTED]"}, 0.05, a2,
+           result="Wrote 642 bytes to docs/draft.md")
+    r.llm(11.35, "Writer", 0.7, a2, prompt=900, completion=30, cost=0.000153, node="agent:Writer",
+          content="Saved the brief to docs/draft.md.")
+    r.emit("agent_end", 12.1, "Writer", {"status": "completed"}, parent_seq=a2, node_id="agent:Writer")
+    r.emit("task_end", 12.15, "Writer", {"status": "completed", "retries": 0, "duration_ms": 5200.0,
+                                          "output_preview": "Saved the brief to docs/draft.md."},
+           parent_seq=t2, node_id="task:write")
+    r.emit("workflow_end", 12.2, "", {"status": "completed", "duration_ms": 12150.0}, parent_seq=w)
+    r.emit("session_end", 12.25, "", {}, parent_seq=s0)
+    r.write("team_handoff.jsonl")
+
+
+def flow_parallel_loop() -> None:
+    """AgentFlow: plan -> parallel(gather news, papers) -> loop(polish x3) -> route(decide) -> publish.
+
+    Both parallel branches run the same agent (Fetcher) so they must appear as
+    two sub-lanes. Includes an unknown event type and an unknown field to prove
+    readers tolerate them.
+    """
+    r = _Run("sess-flow-01", "flow-loop-01")
+    graph = {
+        "schema": "praisonai.graph/1", "kind": "flow", "name": "Weekly digest", "process": "flow",
+        "nodes": [
+            {"id": "start:begin", "kind": "start", "label": "Brief", "parent": None, "meta": {}},
+            {"id": "step:plan", "kind": "step", "label": "plan", "parent": None, "meta": {"agent": "Planner"}},
+            {"id": "step:gather", "kind": "fork", "label": "gather", "parent": None, "meta": {"pattern": "parallel"}},
+            {"id": "step:news", "kind": "step", "label": "news", "parent": "step:gather", "meta": {"agent": "Fetcher"}},
+            {"id": "step:papers", "kind": "step", "label": "papers", "parent": "step:gather", "meta": {"agent": "Fetcher"}},
+            {"id": "step:merge", "kind": "join", "label": "merge", "parent": None, "meta": {}},
+            {"id": "step:review_loop", "kind": "step", "label": "review_loop", "parent": None, "meta": {"pattern": "loop"}},
+            {"id": "step:polish", "kind": "step", "label": "polish", "parent": "step:review_loop", "meta": {"agent": "Editor"}},
+            {"id": "step:decide", "kind": "decision", "label": "decide", "parent": None, "meta": {"pattern": "route"}},
+            {"id": "step:publish", "kind": "step", "label": "publish", "parent": None, "meta": {"agent": "Publisher"}},
+            {"id": "step:archive", "kind": "step", "label": "archive", "parent": None, "meta": {}},
+            {"id": "end:done", "kind": "end", "label": "Delivered", "parent": None, "meta": {}},
+        ],
+        "edges": [
+            {"id": "start:begin->step:plan:next", "source": "start:begin", "target": "step:plan", "kind": "next", "label": None},
+            {"id": "step:plan->step:gather:next", "source": "step:plan", "target": "step:gather", "kind": "next", "label": None},
+            {"id": "step:gather->step:news:parallel", "source": "step:gather", "target": "step:news", "kind": "parallel", "label": None},
+            {"id": "step:gather->step:papers:parallel", "source": "step:gather", "target": "step:papers", "kind": "parallel", "label": None},
+            {"id": "step:news->step:merge:next", "source": "step:news", "target": "step:merge", "kind": "next", "label": None},
+            {"id": "step:papers->step:merge:next", "source": "step:papers", "target": "step:merge", "kind": "next", "label": None},
+            {"id": "step:merge->step:review_loop:next", "source": "step:merge", "target": "step:review_loop", "kind": "next", "label": None},
+            {"id": "step:review_loop->step:polish:loop", "source": "step:review_loop", "target": "step:polish", "kind": "loop", "label": "until approved"},
+            {"id": "step:polish->step:review_loop:loop", "source": "step:polish", "target": "step:review_loop", "kind": "loop", "label": None},
+            {"id": "step:review_loop->step:decide:next", "source": "step:review_loop", "target": "step:decide", "kind": "next", "label": None},
+            {"id": "step:decide->step:publish:routes", "source": "step:decide", "target": "step:publish", "kind": "routes", "label": "publish"},
+            {"id": "step:decide->step:archive:routes", "source": "step:decide", "target": "step:archive", "kind": "routes", "label": "archive"},
+            {"id": "step:publish->end:done:next", "source": "step:publish", "target": "end:done", "kind": "next", "label": None},
+            {"id": "step:archive->end:done:next", "source": "step:archive", "target": "end:done", "kind": "next", "label": None},
+        ],
+    }
+    s0 = r.emit("session_start", 0.0, "", {})
+    w = r.emit("workflow_start", 0.02, "", {"kind": "flow", "name": "Weekly digest", "process": "flow",
+                                           "graph": graph}, parent_seq=s0)
+    sp = r.emit("step_start", 0.05, "Planner", {"name": "plan"}, parent_seq=w, node_id="step:plan")
+    a = r.emit("agent_start", 0.06, "Planner", {}, parent_seq=sp, node_id="agent:Planner")
+    r.llm(0.1, "Planner", 0.8, a, prompt=150, completion=60, cost=0.000059, node="agent:Planner")
+    r.emit("agent_end", 0.95, "Planner", {}, parent_seq=a, node_id="agent:Planner")
+    r.emit("step_end", 1.0, "Planner", {"status": "completed", "duration_ms": 950.0,
+                                         "output_preview": "Gather news and papers."}, parent_seq=sp, node_id="step:plan")
+    g = r.emit("step_start", 1.05, "", {"name": "gather", "pattern": "parallel"}, parent_seq=w, node_id="step:gather")
+    # two branches interleaved in time, same agent
+    b0 = r.emit("step_start", 1.1, "Fetcher", {"name": "news"}, parent_seq=g, node_id="step:news", branch_id="gather/0")
+    b1 = r.emit("step_start", 1.1, "Fetcher", {"name": "papers"}, parent_seq=g, node_id="step:papers", branch_id="gather/1")
+    r.emit("tool_call_start", 1.15, "Fetcher", {"tool_name": "fetch_rss", "tool_args": {"url": "https://example.org/news.rss"}},
+           parent_seq=b0, node_id="tool:Fetcher/fetch_rss", branch_id="gather/0")
+    r.emit("tool_call_start", 1.16, "Fetcher", {"tool_name": "search_papers", "tool_args": {"query": "agent tracing"}},
+           parent_seq=b1, node_id="tool:Fetcher/search_papers", branch_id="gather/1")
+    r.emit("tool_call_end", 2.4, "Fetcher", {"tool_name": "fetch_rss", "result": "12 items", "duration_ms": 1250.0, "error": None},
+           parent_seq=r.seq - 2, node_id="tool:Fetcher/fetch_rss", branch_id="gather/0")
+    r.emit("tool_call_end", 3.0, "Fetcher", {"tool_name": "search_papers", "result": "5 papers", "duration_ms": 1840.0, "error": None},
+           parent_seq=r.seq - 2, node_id="tool:Fetcher/search_papers", branch_id="gather/1", cost_usd=0.001)
+    r.emit("step_end", 2.45, "Fetcher", {"status": "completed", "duration_ms": 1350.0, "output_preview": "12 items"},
+           parent_seq=b0, node_id="step:news", branch_id="gather/0")
+    r.emit("step_end", 3.05, "Fetcher", {"status": "completed", "duration_ms": 1950.0, "output_preview": "5 papers"},
+           parent_seq=b1, node_id="step:papers", branch_id="gather/1")
+    r.emit("step_end", 3.1, "", {"status": "completed", "duration_ms": 2050.0}, parent_seq=g, node_id="step:gather")
+    # an event type this reader has never heard of, plus an unknown field
+    r.emit("context_rebalance", 3.12, "", {"note": "future event type"}, parent_seq=w, future_field={"x": 1})
+    lp = r.emit("step_start", 3.15, "", {"name": "review_loop", "pattern": "loop"}, parent_seq=w, node_id="step:review_loop")
+    t = 3.2
+    for i in range(3):
+        ps = r.emit("step_start", t, "Editor", {"name": "polish", "iteration": i + 1}, parent_seq=lp, node_id="step:polish")
+        r.llm(t + 0.02, "Editor", 0.7, ps, prompt=400 + 50 * i, completion=90, cost=0.000114 + 0.0000075 * i,
+              node="agent:Editor")
+        r.emit("step_end", t + 0.75, "Editor", {"status": "completed", "duration_ms": 750.0,
+                                                 "output_preview": f"Draft v{i + 2}"}, parent_seq=ps, node_id="step:polish")
+        t += 0.8
+    r.emit("step_end", t, "", {"status": "completed", "duration_ms": round((t - 3.15) * 1000, 1)},
+           parent_seq=lp, node_id="step:review_loop")
+    d = r.emit("step_start", t + 0.05, "", {"name": "decide", "pattern": "route"}, parent_seq=w, node_id="step:decide")
+    r.emit("agent_handoff", t + 0.1, "Editor", {"from_agent": "Editor", "to_agent": "Publisher", "kind": "route",
+                                                "reason": "Draft approved by reviewer score 0.92",
+                                                "context_passed": {"score": 0.92}}, parent_seq=d, node_id="step:decide")
+    r.emit("step_end", t + 0.15, "", {"status": "completed", "duration_ms": 100.0, "route": "publish"},
+           parent_seq=d, node_id="step:decide")
+    pb = r.emit("step_start", t + 0.2, "Publisher", {"name": "publish"}, parent_seq=w, node_id="step:publish")
+    r.tool(t + 0.25, "Publisher", "post_to_blog", {"title": "Weekly digest"}, 0.6, pb, result="posted /digest/42")
+    r.emit("step_end", t + 0.9, "Publisher", {"status": "completed", "duration_ms": 700.0, "output_preview": "posted"},
+           parent_seq=pb, node_id="step:publish")
+    r.emit("workflow_end", t + 0.95, "", {"status": "completed", "duration_ms": round((t + 0.93) * 1000, 1)}, parent_seq=w)
+    r.emit("session_end", t + 1.0, "", {}, parent_seq=s0)
+    r.write("flow_parallel_loop.jsonl")
+
+
+def legacy_v10() -> None:
+    """A schema 1.0 file: no run_id, parent_seq, node_id; no workflow events."""
+    r = _Run("legacy-sess-10", None, schema="1.0")
+    r.emit("session_start", 0.0, "", {})
+    r.emit("agent_start", 0.1, "Assistant", {"role": "Assistant"})
+    r.emit("message_added", 0.15, "Assistant", {"role": "user", "content": "What is 17 * 23?"}, messages_count=1)
+    r.llm(0.2, "Assistant", 0.5, None, prompt=90, completion=20, cost=0.000026, finish="tool_calls")
+    r.tool(0.75, "Assistant", "calculator", {"expression": "17*23"}, 0.01, None, result="391")
+    r.llm(0.8, "Assistant", 0.4, None, prompt=130, completion=12, cost=0.000027)
+    r.emit("agent_handoff", 1.25, "Assistant", {"from_agent": "Assistant", "to_agent": "Checker",
+                                                "reason": "Double-check the arithmetic", "context_passed": {"answer": 391}})
+    r.emit("agent_end", 1.26, "Assistant", {})
+    r.emit("agent_start", 1.3, "Checker", {"role": "Checker"})
+    r.llm(1.35, "Checker", 0.45, None, prompt=60, completion=8, cost=0.000014)
+    r.emit("agent_end", 1.85, "Checker", {})
+    r.emit("session_end", 1.9, "", {})
+    r.write("legacy_v10.jsonl")
+
+
+def team_outside() -> None:
+    """Shape of a real recorded run: each agent's LLM span encloses its tool
+    calls (llm_request -> tool -> llm_response), and after the team finishes a
+    Triage agent hands off to Billing, neither of which is in the team graph.
+    """
+    r = _Run("sess-outside-01", "team-outside-01")
+    graph = {
+        "schema": "praisonai.graph/1", "kind": "team", "name": "EV brief", "process": "sequential",
+        "nodes": [
+            {"id": "start:begin", "kind": "start", "label": "Brief", "parent": None, "meta": {}},
+            {"id": "task:research", "kind": "task", "label": "research", "parent": None, "meta": {}},
+            {"id": "task:write", "kind": "task", "label": "write", "parent": None, "meta": {}},
+            {"id": "agent:Researcher", "kind": "agent", "label": "Researcher", "parent": None, "meta": {}},
+            {"id": "agent:Writer", "kind": "agent", "label": "Writer", "parent": None, "meta": {}},
+            {"id": "tool:Researcher/lookup_fact", "kind": "tool", "label": "lookup_fact", "parent": None, "meta": {}},
+            {"id": "end:done", "kind": "end", "label": "Delivered", "parent": None, "meta": {}},
+        ],
+        "edges": [
+            {"id": "start:begin->task:research:next", "source": "start:begin", "target": "task:research", "kind": "next", "label": None},
+            {"id": "task:research->task:write:next", "source": "task:research", "target": "task:write", "kind": "next", "label": None},
+            {"id": "task:research->agent:Researcher:assigned", "source": "task:research", "target": "agent:Researcher", "kind": "assigned", "label": None},
+            {"id": "task:write->agent:Writer:assigned", "source": "task:write", "target": "agent:Writer", "kind": "assigned", "label": None},
+            {"id": "agent:Researcher->tool:Researcher/lookup_fact:uses", "source": "agent:Researcher", "target": "tool:Researcher/lookup_fact", "kind": "uses", "label": None},
+            {"id": "task:write->end:done:next", "source": "task:write", "target": "end:done", "kind": "next", "label": None},
+        ],
+    }
+    s0 = r.emit("session_start", 0.0, "", {})
+    w = r.emit("workflow_start", 0.01, "", {"kind": "team", "name": "EV brief", "process": "sequential", "graph": graph}, parent_seq=s0)
+    t1 = r.emit("task_start", 0.02, "Researcher", {"name": "research", "agent": "Researcher",
+                                                   "description_preview": "Get one fact about electric vehicles"},
+                parent_seq=w, node_id="task:research")
+    a1 = r.emit("agent_start", 0.03, "Researcher", {}, parent_seq=t1, node_id="agent:Researcher")
+    r.emit("llm_request", 0.05, "Researcher", {"model": "gpt-4o-mini"}, parent_seq=a1, node_id="agent:Researcher")
+    ts = r.emit("tool_call_start", 2.6, "Researcher", {"tool_name": "lookup_fact", "tool_args": {"topic": "electric vehicles"}},
+                parent_seq=a1, node_id="tool:Researcher/lookup_fact")
+    r.emit("tool_call_end", 3.5, "Researcher", {"tool_name": "lookup_fact", "result": "EV sales passed 17 million in 2024",
+                                                 "duration_ms": 880.0, "error": None},
+           parent_seq=ts, node_id="tool:Researcher/lookup_fact")
+    r.emit("llm_response", 5.0, "Researcher", {"response_tokens": 14, "duration_ms": 4950.0, "model": "gpt-4o-mini",
+                                                "response_content": "EV sales passed 17 million in 2024."},
+           parent_seq=a1, node_id="agent:Researcher", prompt_tokens=310, completion_tokens=14, cost_usd=0.000055)
+    r.emit("agent_end", 5.01, "Researcher", {}, parent_seq=a1, node_id="agent:Researcher")
+    r.emit("task_end", 5.02, "Researcher", {"status": "completed", "retries": 0, "duration_ms": 5000.0,
+                                             "output_preview": "EV sales passed 17 million in 2024."}, parent_seq=t1, node_id="task:research")
+    t2 = r.emit("task_start", 5.03, "Writer", {"name": "write", "agent": "Writer",
+                                               "description_preview": "Write one sentence using the fact"},
+                parent_seq=w, node_id="task:write")
+    a2 = r.emit("agent_start", 5.04, "Writer", {}, parent_seq=t2, node_id="agent:Writer")
+    r.llm(5.05, "Writer", 1.05, a2, prompt=200, completion=25, cost=0.000045, node="agent:Writer",
+          content="Global EV sales passed 17 million in 2024.")
+    r.emit("agent_end", 6.11, "Writer", {}, parent_seq=a2, node_id="agent:Writer")
+    r.emit("task_end", 6.12, "Writer", {"status": "completed", "retries": 0, "duration_ms": 1090.0,
+                                         "output_preview": "Global EV sales passed 17 million in 2024."}, parent_seq=t2, node_id="task:write")
+    r.emit("workflow_end", 6.13, "", {"status": "completed", "duration_ms": 6120.0}, parent_seq=w)
+    a3 = r.emit("agent_start", 6.2, "Triage", {}, parent_seq=s0, node_id="agent:Triage")
+    r.emit("llm_request", 6.25, "Triage", {"model": "gpt-4o-mini"}, parent_seq=a3, node_id="agent:Triage")
+    tt = r.emit("tool_call_start", 7.7, "Triage", {"tool_name": "transfer_to_billing", "tool_args": {}},
+                parent_seq=a3, node_id="tool:Triage/transfer_to_billing")
+    r.emit("agent_handoff", 7.71, "Triage", {"from_agent": "Triage", "to_agent": "Billing", "kind": "handoff",
+                                             "reason": "Billing question", "context_passed": {"context_policy": "summary"}},
+           parent_seq=tt, node_id="agent:Billing")
+    a4 = r.emit("agent_start", 7.72, "Billing", {}, parent_seq=tt, node_id="agent:Billing")
+    r.llm(7.75, "Billing", 0.92, a4, prompt=150, completion=19, cost=0.00003, node="agent:Billing",
+          content="Please check your statement for a duplicate charge.")
+    r.emit("agent_end", 8.68, "Billing", {}, parent_seq=a4, node_id="agent:Billing")
+    r.emit("tool_call_end", 8.7, "Triage", {"tool_name": "transfer_to_billing", "result": "Handoff successful",
+                                             "duration_ms": 1000.0, "error": None},
+           parent_seq=tt, node_id="tool:Triage/transfer_to_billing")
+    r.emit("llm_response", 9.6, "Triage", {"response_tokens": 22, "duration_ms": 3350.0, "model": "gpt-4o-mini"},
+           parent_seq=a3, node_id="agent:Triage", prompt_tokens=240, completion_tokens=22, cost_usd=0.00005)
+    r.emit("agent_end", 9.61, "Triage", {}, parent_seq=a3, node_id="agent:Triage")
+    r.emit("session_end", 9.7, "", {}, parent_seq=s0)
+    r.write("team_outside.jsonl")
+
+
+if __name__ == "__main__":
+    team_handoff()
+    flow_parallel_loop()
+    legacy_v10()
+    team_outside()

tests/fixtures/replay/team_handoff.jsonl

@@ -0,0 +1,36 @@
+{"schema_version":"1.1","event_type":"session_start","timestamp":1767225600.0,"session_id":"sess-team-01","agent_name":"","sequence_num":0,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"source":"record"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01"}
+{"schema_version":"1.1","event_type":"workflow_start","timestamp":1767225600.05,"session_id":"sess-team-01","agent_name":"","sequence_num":1,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"kind":"team","name":"Solar sail brief","process":"hierarchical","graph":{"schema":"praisonai.graph/1","kind":"team","name":"Solar sail brief","process":"hierarchical","nodes":[{"id":"start:begin","kind":"start","label":"Brief","parent":null,"meta":{}},{"id":"manager:Manager","kind":"manager","label":"Manager","parent":null,"meta":{}},{"id":"task:research","kind":"task","label":"research","parent":null,"meta":{}},{"id":"task:write","kind":"task","label":"write","parent":null,"meta":{}},{"id":"agent:Researcher","kind":"agent","label":"Researcher","parent":null,"meta":{}},{"id":"agent:Writer","kind":"agent","label":"Writer","parent":null,"meta":{}},{"id":"tool:Researcher/web_search","kind":"tool","label":"web_search","parent":null,"meta":{}},{"id":"tool:Writer/write_file","kind":"tool","label":"write_file","parent":null,"meta":{}},{"id":"human:you","kind":"human","label":"You","parent":null,"meta":{}},{"id":"end:done","kind":"end","label":"Delivered","parent":null,"meta":{}}],"edges":[{"id":"start:begin->manager:Manager:next","source":"start:begin","target":"manager:Manager","kind":"next","label":null},{"id":"manager:Manager->task:research:delegates","source":"manager:Manager","target":"task:research","kind":"delegates","label":null},{"id":"manager:Manager->task:write:delegates","source":"manager:Manager","target":"task:write","kind":"delegates","label":null},{"id":"task:write->task:research:depends_on","source":"task:write","target":"task:research","kind":"depends_on","label":null},{"id":"task:research->agent:Researcher:assigned","source":"task:research","target":"agent:Researcher","kind":"assigned","label":null},{"id":"task:write->agent:Writer:assigned","source":"task:write","target":"agent:Writer","kind":"assigned","label":null},{"id":"agent:Researcher->agent:Writer:handoff","source":"agent:Researcher","target":"agent:Writer","kind":"handoff","label":null},{"id":"agent:Researcher->tool:Researcher/web_search:uses","source":"agent:Researcher","target":"tool:Researcher/web_search","kind":"uses","label":null},{"id":"agent:Writer->tool:Writer/write_file:uses","source":"agent:Writer","target":"tool:Writer/write_file","kind":"uses","label":null},{"id":"human:you->tool:Writer/write_file:reviews","source":"human:you","target":"tool:Writer/write_file","kind":"reviews","label":null},{"id":"agent:Writer->end:done:next","source":"agent:Writer","target":"end:done","kind":"next","label":null}]}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":0}
+{"schema_version":"1.1","event_type":"message_added","timestamp":1767225600.1,"session_id":"sess-team-01","agent_name":"","sequence_num":2,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"role":"user","content":"Write a short brief on solar sails."},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":1}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225600.2,"session_id":"sess-team-01","agent_name":"Manager","sequence_num":3,"messages_count":3,"tokens_used":210,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":1,"node_id":"manager:Manager"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225600.8,"session_id":"sess-team-01","agent_name":"Manager","sequence_num":4,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":48,"duration_ms":600.0,"finish_reason":"stop","model":"gpt-4o-mini","response_content":"Delegate research first, then writing."},"prompt_tokens":210,"completion_tokens":48,"cost_usd":6e-05,"run_id":"team-handoff-01","parent_seq":1,"node_id":"manager:Manager"}
+{"schema_version":"1.1","event_type":"agent_handoff","timestamp":1767225600.85,"session_id":"sess-team-01","agent_name":"Manager","sequence_num":5,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"from_agent":"Manager","to_agent":"Researcher","kind":"delegate","reason":"Research has to come before writing.","context_passed":{"task_snapshot":{"task":"research","description":"Find three facts about solar sails","expected_output":"3 bullet facts","status":"not started"}}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":1,"node_id":"manager:Manager"}
+{"schema_version":"1.1","event_type":"task_start","timestamp":1767225600.9,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":6,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"research","agent":"Researcher","description_preview":"Find three facts about solar sails"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":1,"node_id":"task:research"}
+{"schema_version":"1.1","event_type":"agent_start","timestamp":1767225600.95,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":7,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"role":"Researcher","goal":"Find facts"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":6,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"message_added","timestamp":1767225601.0,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":8,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"role":"user","content":"Find three facts about solar sails"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":7}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225601.05,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":9,"messages_count":3,"tokens_used":320,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":7,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225601.95,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":10,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":40,"duration_ms":900.0,"finish_reason":"tool_calls","model":"gpt-4o-mini"},"prompt_tokens":320,"completion_tokens":40,"cost_usd":7.2e-05,"run_id":"team-handoff-01","parent_seq":7,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225602.0,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":11,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"web_search","tool_args":{"query":"solar sail facts"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":7,"node_id":"tool:Researcher/web_search"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225603.2,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":12,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"web_search","result":"IKAROS (2010) was the first interplanetary solar sail.","duration_ms":1200.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.002,"run_id":"team-handoff-01","parent_seq":11,"node_id":"tool:Researcher/web_search"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225603.25,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":13,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"web_search","tool_args":{"query":"solar sail missions"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":7,"node_id":"tool:Researcher/web_search"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225604.35,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":14,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"web_search","result":"LightSail 2 raised its orbit using sunlight in 2019.","duration_ms":1100.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.002,"run_id":"team-handoff-01","parent_seq":13,"node_id":"tool:Researcher/web_search"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225604.4,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":15,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"web_search","tool_args":{"query":"solar sail physics"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":7,"node_id":"tool:Researcher/web_search"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225605.3,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":16,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"web_search","result":"Photon pressure at 1 AU is about 9 micronewtons per square metre.","duration_ms":900.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.002,"run_id":"team-handoff-01","parent_seq":15,"node_id":"tool:Researcher/web_search"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225605.35,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":17,"messages_count":3,"tokens_used":880,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":7,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225606.75,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":18,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":160,"duration_ms":1400.0,"finish_reason":"stop","model":"gpt-4o-mini","response_content":"1. IKAROS ... 2. LightSail 2 ... 3. ~9 uN/m^2"},"prompt_tokens":880,"completion_tokens":160,"cost_usd":0.000228,"run_id":"team-handoff-01","parent_seq":7,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"agent_end","timestamp":1767225606.8,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":19,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":7,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"task_end","timestamp":1767225606.85,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":20,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","retries":0,"duration_ms":5950.0,"output_preview":"1. IKAROS ... 2. LightSail 2 ... 3. ~9 uN/m^2"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":6,"node_id":"task:research"}
+{"schema_version":"1.1","event_type":"agent_handoff","timestamp":1767225606.9,"session_id":"sess-team-01","agent_name":"Researcher","sequence_num":21,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"from_agent":"Researcher","to_agent":"Writer","kind":"handoff","reason":"Facts gathered; needs drafting.","context_passed":{"facts":["IKAROS 2010","LightSail 2 2019","~9 uN/m^2 at 1 AU"]}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":1,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"task_start","timestamp":1767225606.95,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":22,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"write","agent":"Writer","description_preview":"Draft a 100-word brief into draft.md"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":1,"node_id":"task:write"}
+{"schema_version":"1.1","event_type":"agent_start","timestamp":1767225607.0,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":23,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"role":"Writer"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":22,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225607.05,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":24,"messages_count":3,"tokens_used":640,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":23,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225608.65,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":25,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":220,"duration_ms":1600.0,"finish_reason":"tool_calls","model":"gpt-4o-mini"},"prompt_tokens":640,"completion_tokens":220,"cost_usd":0.000228,"run_id":"team-handoff-01","parent_seq":23,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"approval_requested","timestamp":1767225608.7,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":26,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"approval_id":"appr-0001","tool":"write_file","args":{"path":"draft.md","content":"[REDACTED]"},"risk":"high","kind":"tool_call"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":23,"node_id":"tool:Writer/write_file"}
+{"schema_version":"1.1","event_type":"approval_decided","timestamp":1767225611.2,"session_id":"sess-team-01","agent_name":"","sequence_num":27,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"approval_id":"appr-0001","approved":true,"reason":"Use the docs folder.","approver":"user","modified":true},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":26,"node_id":"tool:Writer/write_file"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225611.25,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":28,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"write_file","tool_args":{"path":"docs/draft.md","content":"[REDACTED]"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":23,"node_id":"tool:Writer/write_file"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225611.3,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":29,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"write_file","result":"Wrote 642 bytes to docs/draft.md","duration_ms":50.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":28,"node_id":"tool:Writer/write_file"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225611.35,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":30,"messages_count":3,"tokens_used":900,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":23,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225612.05,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":31,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":30,"duration_ms":700.0,"finish_reason":"stop","model":"gpt-4o-mini","response_content":"Saved the brief to docs/draft.md."},"prompt_tokens":900,"completion_tokens":30,"cost_usd":0.000153,"run_id":"team-handoff-01","parent_seq":23,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"agent_end","timestamp":1767225612.1,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":32,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":23,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"task_end","timestamp":1767225612.15,"session_id":"sess-team-01","agent_name":"Writer","sequence_num":33,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","retries":0,"duration_ms":5200.0,"output_preview":"Saved the brief to docs/draft.md."},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":22,"node_id":"task:write"}
+{"schema_version":"1.1","event_type":"workflow_end","timestamp":1767225612.2,"session_id":"sess-team-01","agent_name":"","sequence_num":34,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":12150.0},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":1}
+{"schema_version":"1.1","event_type":"session_end","timestamp":1767225612.25,"session_id":"sess-team-01","agent_name":"","sequence_num":35,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-handoff-01","parent_seq":0}

tests/fixtures/replay/team_outside.jsonl

@@ -0,0 +1,29 @@
+{"schema_version":"1.1","event_type":"session_start","timestamp":1767225600.0,"session_id":"sess-outside-01","agent_name":"","sequence_num":0,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01"}
+{"schema_version":"1.1","event_type":"workflow_start","timestamp":1767225600.01,"session_id":"sess-outside-01","agent_name":"","sequence_num":1,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"kind":"team","name":"EV brief","process":"sequential","graph":{"schema":"praisonai.graph/1","kind":"team","name":"EV brief","process":"sequential","nodes":[{"id":"start:begin","kind":"start","label":"Brief","parent":null,"meta":{}},{"id":"task:research","kind":"task","label":"research","parent":null,"meta":{}},{"id":"task:write","kind":"task","label":"write","parent":null,"meta":{}},{"id":"agent:Researcher","kind":"agent","label":"Researcher","parent":null,"meta":{}},{"id":"agent:Writer","kind":"agent","label":"Writer","parent":null,"meta":{}},{"id":"tool:Researcher/lookup_fact","kind":"tool","label":"lookup_fact","parent":null,"meta":{}},{"id":"end:done","kind":"end","label":"Delivered","parent":null,"meta":{}}],"edges":[{"id":"start:begin->task:research:next","source":"start:begin","target":"task:research","kind":"next","label":null},{"id":"task:research->task:write:next","source":"task:research","target":"task:write","kind":"next","label":null},{"id":"task:research->agent:Researcher:assigned","source":"task:research","target":"agent:Researcher","kind":"assigned","label":null},{"id":"task:write->agent:Writer:assigned","source":"task:write","target":"agent:Writer","kind":"assigned","label":null},{"id":"agent:Researcher->tool:Researcher/lookup_fact:uses","source":"agent:Researcher","target":"tool:Researcher/lookup_fact","kind":"uses","label":null},{"id":"task:write->end:done:next","source":"task:write","target":"end:done","kind":"next","label":null}]}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":0}
+{"schema_version":"1.1","event_type":"task_start","timestamp":1767225600.02,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":2,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"research","agent":"Researcher","description_preview":"Get one fact about electric vehicles"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":1,"node_id":"task:research"}
+{"schema_version":"1.1","event_type":"agent_start","timestamp":1767225600.03,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":3,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":2,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225600.05,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":4,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":3,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225602.6,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":5,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"lookup_fact","tool_args":{"topic":"electric vehicles"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":3,"node_id":"tool:Researcher/lookup_fact"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225603.5,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":6,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"lookup_fact","result":"EV sales passed 17 million in 2024","duration_ms":880.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":5,"node_id":"tool:Researcher/lookup_fact"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225605.0,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":7,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":14,"duration_ms":4950.0,"model":"gpt-4o-mini","response_content":"EV sales passed 17 million in 2024."},"prompt_tokens":310,"completion_tokens":14,"cost_usd":5.5e-05,"run_id":"team-outside-01","parent_seq":3,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"agent_end","timestamp":1767225605.01,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":8,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":3,"node_id":"agent:Researcher"}
+{"schema_version":"1.1","event_type":"task_end","timestamp":1767225605.02,"session_id":"sess-outside-01","agent_name":"Researcher","sequence_num":9,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","retries":0,"duration_ms":5000.0,"output_preview":"EV sales passed 17 million in 2024."},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":2,"node_id":"task:research"}
+{"schema_version":"1.1","event_type":"task_start","timestamp":1767225605.03,"session_id":"sess-outside-01","agent_name":"Writer","sequence_num":10,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"name":"write","agent":"Writer","description_preview":"Write one sentence using the fact"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":1,"node_id":"task:write"}
+{"schema_version":"1.1","event_type":"agent_start","timestamp":1767225605.04,"session_id":"sess-outside-01","agent_name":"Writer","sequence_num":11,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":10,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225605.05,"session_id":"sess-outside-01","agent_name":"Writer","sequence_num":12,"messages_count":3,"tokens_used":200,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":11,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225606.1,"session_id":"sess-outside-01","agent_name":"Writer","sequence_num":13,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":25,"duration_ms":1050.0,"finish_reason":"stop","model":"gpt-4o-mini","response_content":"Global EV sales passed 17 million in 2024."},"prompt_tokens":200,"completion_tokens":25,"cost_usd":4.5e-05,"run_id":"team-outside-01","parent_seq":11,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"agent_end","timestamp":1767225606.11,"session_id":"sess-outside-01","agent_name":"Writer","sequence_num":14,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":11,"node_id":"agent:Writer"}
+{"schema_version":"1.1","event_type":"task_end","timestamp":1767225606.12,"session_id":"sess-outside-01","agent_name":"Writer","sequence_num":15,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","retries":0,"duration_ms":1090.0,"output_preview":"Global EV sales passed 17 million in 2024."},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":10,"node_id":"task:write"}
+{"schema_version":"1.1","event_type":"workflow_end","timestamp":1767225606.13,"session_id":"sess-outside-01","agent_name":"","sequence_num":16,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"status":"completed","duration_ms":6120.0},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":1}
+{"schema_version":"1.1","event_type":"agent_start","timestamp":1767225606.2,"session_id":"sess-outside-01","agent_name":"Triage","sequence_num":17,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":0,"node_id":"agent:Triage"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225606.25,"session_id":"sess-outside-01","agent_name":"Triage","sequence_num":18,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":17,"node_id":"agent:Triage"}
+{"schema_version":"1.1","event_type":"tool_call_start","timestamp":1767225607.7,"session_id":"sess-outside-01","agent_name":"Triage","sequence_num":19,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"transfer_to_billing","tool_args":{}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":17,"node_id":"tool:Triage/transfer_to_billing"}
+{"schema_version":"1.1","event_type":"agent_handoff","timestamp":1767225607.71,"session_id":"sess-outside-01","agent_name":"Triage","sequence_num":20,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"from_agent":"Triage","to_agent":"Billing","kind":"handoff","reason":"Billing question","context_passed":{"context_policy":"summary"}},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":19,"node_id":"agent:Billing"}
+{"schema_version":"1.1","event_type":"agent_start","timestamp":1767225607.72,"session_id":"sess-outside-01","agent_name":"Billing","sequence_num":21,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":19,"node_id":"agent:Billing"}
+{"schema_version":"1.1","event_type":"llm_request","timestamp":1767225607.75,"session_id":"sess-outside-01","agent_name":"Billing","sequence_num":22,"messages_count":3,"tokens_used":150,"tokens_budget":128000,"data":{"model":"gpt-4o-mini"},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":21,"node_id":"agent:Billing"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225608.67,"session_id":"sess-outside-01","agent_name":"Billing","sequence_num":23,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":19,"duration_ms":920.0,"finish_reason":"stop","model":"gpt-4o-mini","response_content":"Please check your statement for a duplicate charge."},"prompt_tokens":150,"completion_tokens":19,"cost_usd":3e-05,"run_id":"team-outside-01","parent_seq":21,"node_id":"agent:Billing"}
+{"schema_version":"1.1","event_type":"agent_end","timestamp":1767225608.68,"session_id":"sess-outside-01","agent_name":"Billing","sequence_num":24,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":21,"node_id":"agent:Billing"}
+{"schema_version":"1.1","event_type":"tool_call_end","timestamp":1767225608.7,"session_id":"sess-outside-01","agent_name":"Triage","sequence_num":25,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"tool_name":"transfer_to_billing","result":"Handoff successful","duration_ms":1000.0,"error":null},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":19,"node_id":"tool:Triage/transfer_to_billing"}
+{"schema_version":"1.1","event_type":"llm_response","timestamp":1767225609.6,"session_id":"sess-outside-01","agent_name":"Triage","sequence_num":26,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{"response_tokens":22,"duration_ms":3350.0,"model":"gpt-4o-mini"},"prompt_tokens":240,"completion_tokens":22,"cost_usd":5e-05,"run_id":"team-outside-01","parent_seq":17,"node_id":"agent:Triage"}
+{"schema_version":"1.1","event_type":"agent_end","timestamp":1767225609.61,"session_id":"sess-outside-01","agent_name":"Triage","sequence_num":27,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":17,"node_id":"agent:Triage"}
+{"schema_version":"1.1","event_type":"session_end","timestamp":1767225609.7,"session_id":"sess-outside-01","agent_name":"","sequence_num":28,"messages_count":0,"tokens_used":0,"tokens_budget":0,"data":{},"prompt_tokens":0,"completion_tokens":0,"cost_usd":0.0,"run_id":"team-outside-01","parent_seq":0}

tests/js/replay-core.test.mjs

@@ -0,0 +1,509 @@
+// node --test tests/js/replay-core.test.mjs
+// Pure-function tests for the PraisonAI Replay model (no DOM, no network).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, '..', '..');
+const coreUrl = pathToFileURL(path.join(root, 'src/praisonaiui/templates/frontend/plugins/views/replay-core.js'));
+const core = await import(coreUrl.href);
+const { buildModel, narrate, layoutMap, deriveGraph, formatCost, formatDuration } = core;
+
+function load(name) {
+  const text = fs.readFileSync(path.join(root, 'tests/fixtures/replay', `${name}.jsonl`), 'utf8');
+  const events = text.split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  const ws = events.find((e) => e.event_type === 'workflow_start');
+  return { events, graph: ws && ws.data && ws.data.graph ? ws.data.graph : null };
+}
+
+// ── buildModel: lanes ────────────────────────────────────────────────
+
+test('team run: You and Manager lanes come first, agents follow graph order', () => {
+  const { events, graph } = load('team_handoff');
+  const m = buildModel(events, graph);
+  assert.deepEqual(m.lanes.map((l) => l.id), ['human:you', 'manager:Manager', 'agent:Researcher', 'agent:Writer']);
+  assert.deepEqual(m.lanes.map((l) => l.shape), ['diamond', 'square', 'circle', 'circle']);
+  assert.equal(m.lanes[0].label, 'You');
+});
+
+test('parallel branches of one agent become sub-lanes labelled by step', () => {
+  const { events, graph } = load('flow_parallel_loop');
+  const m = buildModel(events, graph);
+  const subs = m.lanes.filter((l) => l.parent === 'agent:Fetcher');
+  assert.deepEqual(subs.map((l) => [l.id, l.branch, l.label]), [
+    ['agent:Fetcher#gather/0', 'gather/0', 'news'],
+    ['agent:Fetcher#gather/1', 'gather/1', 'papers'],
+  ]);
+  const tools = m.blocks.filter((b) => b.kind === 'tool' && b.agent === 'Fetcher');
+  assert.deepEqual(tools.map((b) => b.lane), ['agent:Fetcher#gather/0', 'agent:Fetcher#gather/1']);
+  // the two branches overlap in time: that is why they need their own rows
+  assert.ok(tools[1].start < tools[0].end);
+});
+
+test('a 1.0 legacy file still yields lanes, blocks and a hand-off', () => {
+  const { events } = load('legacy_v10');
+  const m = buildModel(events, null);
+  assert.deepEqual(m.lanes.map((l) => l.id), ['human:you', 'agent:Assistant', 'agent:Checker']);
+  assert.deepEqual(m.blocks.map((b) => `${b.kind}:${b.label}`), ['llm:gpt-4o-mini', 'tool:calculator', 'llm:gpt-4o-mini', 'llm:gpt-4o-mini']);
+  assert.equal(m.arrows.length, 1);
+  assert.equal(m.arrows[0].kind, 'handoff');
+  assert.equal(m.chapters.length, 0);
+});
+
+// ── buildModel: arrows ───────────────────────────────────────────────
+
+test('delegate and hand-off arrows connect the right lanes', () => {
+  const { events, graph } = load('team_handoff');
+  const m = buildModel(events, graph);
+  const flows = m.arrows.map((a) => `${a.kind}:${a.from}->${a.to}`);
+  assert.deepEqual(flows, [
+    'delegate:manager:Manager->agent:Researcher',
+    'handoff:agent:Researcher->agent:Writer',
+    'ask:agent:Writer->human:you',
+    'answer:human:you->agent:Writer',
+  ]);
+  assert.equal(m.arrows[0].label, 'delegates');
+  assert.equal(m.arrows[3].label, 'approved');
+});
+
+test('route arrows from a flow', () => {
+  const { events, graph } = load('flow_parallel_loop');
+  const m = buildModel(events, graph);
+  assert.deepEqual(m.arrows.map((a) => [a.kind, a.from, a.to]), [['route', 'agent:Editor', 'agent:Publisher']]);
+});
+
+// ── buildModel: xN collapse ──────────────────────────────────────────
+
+test('three consecutive web_search calls collapse to one block x3', () => {
+  const { events, graph } = load('team_handoff');
+  const m = buildModel(events, graph);
+  const ws = m.blocks.filter((b) => b.label === 'web_search');
+  assert.equal(ws.length, 1);
+  assert.equal(ws[0].count, 3);
+  assert.equal(ws[0].members.length, 3);
+  assert.ok(Math.abs(ws[0].cost - 0.006) < 1e-9);
+  assert.ok(Math.abs(ws[0].durationMs - 3200) < 1e-6);
+  // every member's events map to the collapsed block
+  const lines = m.narration.filter((n) => n.text.includes('web_search'));
+  assert.equal(lines.length, 3);
+  assert.ok(lines.every((n) => n.blockId === ws[0].id));
+});
+
+test('loop passes collapse: polish chapter x3 and Editor LLM block x3', () => {
+  const { events, graph } = load('flow_parallel_loop');
+  const m = buildModel(events, graph);
+  const polish = m.chapters.filter((c) => c.nodeId === 'step:polish');
+  assert.equal(polish.length, 1);
+  assert.equal(polish[0].count, 3);
+  assert.equal(polish[0].depth, 1);
+  const editor = m.blocks.filter((b) => b.agent === 'Editor');
+  assert.equal(editor.length, 1);
+  assert.equal(editor[0].count, 3);
+  assert.equal(editor[0].tokens, 490 + 540 + 590);
+});
+
+test('non-adjacent repeats are not collapsed', () => {
+  const { events, graph } = load('team_handoff');
+  const m = buildModel(events, graph);
+  const researcherLlm = m.blocks.filter((b) => b.agent === 'Researcher' && b.kind === 'llm');
+  assert.equal(researcherLlm.length, 2); // llm, tool x3, llm
+  assert.ok(researcherLlm.every((b) => b.count === 1));
+});
+
+// ── buildModel: chapters, approvals, totals, live ────────────────────
+
+test('chapters carry depth, rows and the chosen route', () => {
+  const { events, graph } = load('flow_parallel_loop');
+  const m = buildModel(events, graph);
+  const byNode = Object.fromEntries(m.chapters.map((c) => [c.nodeId, c]));
+  assert.equal(byNode['step:gather'].depth, 0);
+  assert.equal(byNode['step:news'].depth, 1);
+  assert.notEqual(byNode['step:news'].row, byNode['step:papers'].row); // overlapping -> own rows
+  assert.equal(byNode['step:decide'].route, 'publish');
+  assert.equal(m.chapterRows, 3);
+});
+
+test('approval sits in the You lane with its decision', () => {
+  const { events, graph } = load('team_handoff');
+  const m = buildModel(events, graph);
+  const ap = m.blocks.find((b) => b.kind === 'approval');
+  assert.equal(ap.lane, 'human:you');
+  assert.equal(ap.status, 'approved');
+  assert.equal(ap.approvalId, 'appr-0001');
+  assert.equal(m.pending.length, 0);
+});
+
+test('a run cut before the decision has one pending approval and open blocks', () => {
+  const { events, graph } = load('team_handoff');
+  const cut = events.slice(0, events.findIndex((e) => e.event_type === 'approval_decided'));
+  const m = buildModel(cut, graph);
+  assert.equal(m.pending.length, 1);
+  assert.equal(m.pending[0].approvalId, 'appr-0001');
+  assert.equal(m.pending[0].open, true);
+  const half = events.slice(0, events.findIndex((e) => e.event_type === 'tool_call_end'));
+  const m2 = buildModel(half, graph);
+  const running = m2.blocks.find((b) => b.kind === 'tool');
+  assert.equal(running.open, true);
+  assert.equal(running.status, 'running');
+  assert.match(m2.narration.at(-1).text, /^Researcher is asking web_search for 'solar sail facts'…$/);
+});
+
+test('totals per agent and for the run', () => {
+  const { events, graph } = load('team_handoff');
+  const m = buildModel(events, graph);
+  assert.equal(m.totals.llm_calls, 5);
+  assert.equal(m.totals.tool_calls, 4);
+  assert.ok(Math.abs(m.totals.cost_usd - 0.006741) < 1e-9);
+  const r = m.totals.agents['agent:Researcher'];
+  assert.ok(Math.abs(r.cost_usd - (0.000072 + 0.006 + 0.000228)) < 1e-9);
+  assert.equal(r.tool_calls, 3);
+  assert.ok(Math.abs(m.totals.duration_ms - 12250) < 1e-6);
+});
+
+test('sub-lane work rolls up to the parent agent total', () => {
+  const { events, graph } = load('flow_parallel_loop');
+  const m = buildModel(events, graph);
+  const f = m.totals.agents['agent:Fetcher'];
+  assert.equal(f.tool_calls, 2);
+  assert.ok(Math.abs(f.cost_usd - 0.001) < 1e-9);
+  assert.equal(m.totals.agents['agent:Fetcher#gather/0'], undefined);
+});
+
+test('unknown event types and fields are tolerated and skipped', () => {
+  const { events, graph } = load('flow_parallel_loop');
+  assert.ok(events.some((e) => e.event_type === 'context_rebalance'));
+  const m = buildModel(events, graph);
+  assert.ok(!m.narration.some((n) => n.type === 'context_rebalance'));
+  assert.equal(m.events.length, events.length);
+});
+
+test('duplicates (same session:seq, e.g. after an SSE reconnect) are dropped; order follows sequence_num', () => {
+  const { events, graph } = load('legacy_v10');
+  const shuffled = [...events].reverse().concat(events.slice(0, 3));
+  const m = buildModel(shuffled, graph);
+  assert.equal(m.events.length, events.length);
+  assert.deepEqual(m.events.map((e) => e.sequence_num), events.map((e) => e.sequence_num));
+});
+
+test('empty input is fine', () => {
+  const m = buildModel([], null);
+  assert.equal(m.blocks.length, 0);
+  assert.equal(m.narration.length, 0);
+  assert.deepEqual(m.lanes.map((l) => l.id), ['human:you']);
+});
+
+// ── narrate ──────────────────────────────────────────────────────────
+
+const ev = (event_type, data = {}, extra = {}) => ({ event_type, data, agent_name: 'Researcher', timestamp: 100, sequence_num: 1, session_id: 's', ...extra });
+
+test('narrate: tool call with its end gives duration and cost', () => {
+  const start = ev('tool_call_start', { tool_name: 'web_search', tool_args: { query: 'X' } });
+  const end = ev('tool_call_end', { tool_name: 'web_search', duration_ms: 1200 }, { cost_usd: 0.002, timestamp: 101.2 });
+  assert.equal(narrate(start, end), "Researcher asked web_search for 'X' — 1.2 s, $0.002.");
+  assert.equal(narrate(start), "Researcher is asking web_search for 'X'…");
+  const failed = ev('tool_call_end', { tool_name: 'web_search', duration_ms: 300, error: 'HTTP 500' });
+  assert.equal(narrate(start, failed), "Researcher asked web_search for 'X' — failed after 300 ms: HTTP 500.");
+});
+
+test('narrate: hand-off kinds', () => {
+  assert.equal(
+    narrate(ev('agent_handoff', { from_agent: 'Researcher', to_agent: 'Writer', reason: 'Facts gathered.' })),
+    "Researcher handed off to Writer: 'Facts gathered'.",
+  );
+  assert.equal(narrate(ev('agent_handoff', { from_agent: 'Manager', to_agent: 'Writer', kind: 'delegate' }, { agent_name: 'Manager' })), 'Manager delegated to Writer.');
+  assert.equal(narrate(ev('agent_handoff', { from_agent: 'A', to_agent: 'B', kind: 'route' })), 'A routed to B.');
+  assert.equal(narrate(ev('agent_handoff', { from_agent: 'A', to_agent: 'B', kind: 'spawn' })), 'A spawned B.');
+  assert.equal(narrate(ev('agent_handoff', { from_agent: 'A', to_agent: 'B', kind: 'weird' })), 'A handed off to B.');
+});
+
+test('narrate: LLM response with model, tokens, cost', () => {
+  const r = ev('llm_response', { duration_ms: 900, model: 'gpt-4o-mini' }, { prompt_tokens: 120, completion_tokens: 40, cost_usd: 0.0004 });
+  assert.equal(narrate(r), 'Researcher thought with gpt-4o-mini — 900 ms, 160 tokens, $0.0004.');
+});
+
+test('narrate: approvals, human and automatic', () => {
+  const req = ev('approval_requested', { approval_id: 'a1', tool: 'write_file', risk: 'high', kind: 'tool_call' }, { agent_name: 'Writer' });
+  assert.equal(narrate(req), 'Writer asked you to approve write_file (high risk).');
+  assert.equal(narrate(ev('approval_decided', { approved: true, approver: 'user', modified: true }), req), 'You approved write_file with edited arguments.');
+  assert.equal(narrate(ev('approval_decided', { approved: true, approver: 'env' }), req), 'write_file was approved automatically (env).');
+  assert.equal(narrate(ev('approval_decided', { approved: false, approver: 'user', reason: 'Not now' }), req), "You denied write_file: 'Not now'.");
+  assert.equal(narrate(ev('approval_decided', { approved: false, approver: 'timeout' }), req), 'write_file was denied: no answer before the timeout.');
+});
+
+test('narrate: tasks, steps, routes, workflow', () => {
+  assert.equal(narrate(ev('task_start', { name: 'research', agent: 'Researcher' })), "Task 'research' went to Researcher.");
+  assert.equal(narrate(ev('task_end', { status: 'failed', duration_ms: 2500, retries: 2 }, { node_id: 'task:research' })), "Task 'research' failed after 2.5 s, 2 retries.");
+  assert.equal(narrate(ev('step_end', { route: 'publish' }), ev('step_start', { name: 'decide' })), "Step 'decide' chose route 'publish'.");
+  assert.equal(narrate(ev('step_end', { status: 'cached' }, { node_id: 'step:fetch' })), "Step 'fetch' reused a cached result.");
+  assert.equal(narrate(ev('step_start', { name: 'gather', pattern: 'parallel' })), "Step 'gather' fanned out in parallel.");
+  assert.equal(narrate(ev('workflow_start', { kind: 'team', name: 'Brief', process: 'hierarchical' })), "Team 'Brief' started (hierarchical).");
+  assert.equal(narrate(ev('workflow_end', { status: 'completed', duration_ms: 125000 })), 'The run completed after 2 min 05 s.');
+});
+
+test('narrate: unknown and quiet events give empty strings', () => {
+  assert.equal(narrate(ev('context_snapshot')), '');
+  assert.equal(narrate(ev('something_new')), '');
+  assert.equal(narrate(null), '');
+  assert.equal(narrate(ev('message_added', { role: 'assistant', content: 'hi' })), '');
+  assert.equal(narrate(ev('message_added', { role: 'user', content: 'Hello!' }, { agent_name: '' })), "You said: 'Hello'.");
+});
+
+test('narrate is deterministic', () => {
+  const { events, graph } = load('team_handoff');
+  const a = buildModel(events, graph).narration.map((n) => n.text);
+  const b = buildModel(events, graph).narration.map((n) => n.text);
+  assert.deepEqual(a, b);
+  assert.ok(a.includes("Researcher asked web_search for 'solar sail facts' — 1.2 s, $0.002."));
+});
+
+test('formatters', () => {
+  assert.equal(formatDuration(850), '850 ms');
+  assert.equal(formatDuration(1200), '1.2 s');
+  assert.equal(formatCost(0.002), '$0.002');
+  assert.equal(formatCost(0.00001), '<$0.0001');
+  assert.equal(formatCost(1.5), '$1.50');
+  assert.equal(formatCost(0), '');
+});
+
+// ── layoutMap / deriveGraph ──────────────────────────────────────────
+
+test('layoutMap: layers flow left to right and every node gets a box', () => {
+  const { graph } = load('team_handoff');
+  const lay = layoutMap(graph);
+  const byId = Object.fromEntries(lay.nodes.map((n) => [n.id, n]));
+  assert.equal(lay.nodes.length, graph.nodes.length);
+  assert.ok(byId['start:begin'].layer < byId['manager:Manager'].layer);
+  assert.ok(byId['manager:Manager'].layer < byId['task:research'].layer);
+  // depends_on (write depends on research) puts research first
+  assert.ok(byId['task:research'].layer < byId['task:write'].layer);
+  assert.ok(byId['agent:Researcher'].layer < byId['agent:Writer'].layer);
+  for (const n of lay.nodes) {
+    assert.ok(n.x >= 0 && n.y >= 0 && n.x + n.w <= lay.width && n.y + n.h <= lay.height, n.id);
+  }
+  assert.deepEqual([...new Set(lay.nodes.map((n) => n.shape))].sort(), ['chevron', 'circle', 'diamond', 'flag', 'note', 'rounded', 'square']);
+});
+
+test('layoutMap: no two nodes overlap', () => {
+  for (const name of ['team_handoff', 'flow_parallel_loop']) {
+    const lay = layoutMap(load(name).graph);
+    for (let i = 0; i < lay.nodes.length; i++) {
+      for (let j = i + 1; j < lay.nodes.length; j++) {
+        const a = lay.nodes[i];
+        const b = lay.nodes[j];
+        const apart = a.x + a.w <= b.x || b.x + b.w <= a.x || a.y + a.h <= b.y || b.y + b.h <= a.y;
+        assert.ok(apart, `${a.id} overlaps ${b.id}`);
+      }
+    }
+  }
+});
+
+test('layoutMap: a loop edge is a back edge, routed underneath, labels kept', () => {
+  const lay = layoutMap(load('flow_parallel_loop').graph);
+  const back = lay.edges.filter((e) => e.back);
+  assert.deepEqual(back.map((e) => e.id), ['step:polish->step:review_loop:loop']);
+  assert.equal(back[0].points.length, 4);
+  const routes = lay.edges.filter((e) => e.kind === 'routes').map((e) => e.label).sort();
+  assert.deepEqual(routes, ['archive', 'publish']);
+  assert.equal(core.edgeText(lay.edges.find((e) => e.kind === 'routes' && e.label === 'publish')), 'routes: publish');
+});
+
+test('layoutMap: deterministic and tolerant of bad input', () => {
+  const g = load('flow_parallel_loop').graph;
+  assert.deepEqual(layoutMap(g), layoutMap(g));
+  const empty = layoutMap(null);
+  assert.equal(empty.nodes.length, 0);
+  const dangling = layoutMap({ nodes: [{ id: 'agent:A', kind: 'agent' }], edges: [{ source: 'agent:A', target: 'nope', kind: 'next' }] });
+  assert.equal(dangling.edges.length, 0);
+});
+
+test('deriveGraph: who talked to whom for a 1.0 file', () => {
+  const g = deriveGraph(load('legacy_v10').events);
+  assert.equal(g.derived, true);
+  assert.deepEqual(g.nodes.map((n) => n.id).sort(), ['agent:Assistant', 'agent:Checker', 'tool:Assistant/calculator']);
+  assert.deepEqual(g.edges.map((e) => e.id).sort(), [
+    'agent:Assistant->agent:Checker:handoff',
+    'agent:Assistant->tool:Assistant/calculator:uses',
+  ]);
+  const lay = layoutMap(g);
+  assert.equal(lay.nodes.length, 3);
+});
+
+test('deriveGraph counts repeats and includes you for approvals', () => {
+  const { events } = load('team_handoff');
+  const g = deriveGraph(events);
+  const ws = g.edges.find((e) => e.id === 'agent:Researcher->tool:Researcher/web_search:uses');
+  assert.equal(ws.label, '×3');
+  assert.ok(g.nodes.some((n) => n.id === 'human:you' && n.kind === 'human'));
+  assert.ok(g.edges.some((e) => e.kind === 'delegates' && e.source === 'manager:Manager'));
+});
+
+test('module also registers itself on globalThis for the standalone build', () => {
+  assert.equal(typeof globalThis.PraisonReplayCore.buildModel, 'function');
+});
+
+// ── observed graph / run map ─────────────────────────────────────────
+
+test('observedGraph: agents seen in events but not in the graph are "outside"', () => {
+  const { events, graph } = load('team_outside');
+  const g = core.observedGraph(graph, events);
+  assert.deepEqual([...g.outside].sort(), ['agent:Billing', 'agent:Triage', 'tool:Triage/transfer_to_billing']);
+  // team members keep their recorded ids; nothing duplicated
+  assert.equal(g.nodes.filter((n) => n.id === 'agent:Researcher').length, 1);
+  assert.ok(g.edges.some((e) => e.id === 'agent:Triage->agent:Billing:handoff' && e.meta.observed));
+  // the recorded uses-edge is not added twice
+  assert.equal(g.edges.filter((e) => e.source === 'agent:Researcher' && e.target === 'tool:Researcher/lookup_fact').length, 1);
+});
+
+test('observedGraph without a recorded graph is the derived map', () => {
+  const { events } = load('legacy_v10');
+  assert.equal(core.observedGraph(null, events).derived, true);
+});
+
+test('layoutRunMap: outside agents form their own framed block under the team', () => {
+  const { events, graph } = load('team_outside');
+  const lay = core.layoutRunMap(graph, events);
+  assert.equal(lay.groups.length, 1);
+  const grp = lay.groups[0];
+  assert.equal(grp.label, 'Outside the team');
+  const inside = lay.nodes.filter((n) => !n.outside);
+  const outside = lay.nodes.filter((n) => n.outside);
+  assert.deepEqual(outside.map((n) => n.id).sort(), ['agent:Billing', 'agent:Triage', 'tool:Triage/transfer_to_billing']);
+  const teamBottom = Math.max(...inside.map((n) => n.y + n.h));
+  for (const n of outside) {
+    assert.ok(n.y > teamBottom, `${n.id} sits below the team`);
+    assert.ok(n.x >= grp.x && n.x + n.w <= grp.x + grp.w && n.y >= grp.y && n.y + n.h <= grp.y + grp.h, `${n.id} inside the frame`);
+  }
+  for (const n of lay.nodes) assert.ok(n.x + n.w <= lay.width && n.y + n.h <= lay.height, `${n.id} within bounds`);
+  assert.ok(lay.edges.some((e) => e.id === 'agent:Triage->agent:Billing:handoff'));
+});
+
+test('layoutRunMap: no outside group when the graph covers everyone', () => {
+  const { events, graph } = load('team_handoff');
+  const lay = core.layoutRunMap(graph, events);
+  assert.equal(lay.groups.length, 0);
+  assert.equal(lay.nodes.length, graph.nodes.length);
+});
+
+test('real-run shape: LLM span encloses the tool call in the same lane', () => {
+  const { events, graph } = load('team_outside');
+  const m = buildModel(events, graph);
+  const llm = m.blocks.find((b) => b.agent === 'Researcher' && b.kind === 'llm');
+  const tool = m.blocks.find((b) => b.agent === 'Researcher' && b.kind === 'tool');
+  assert.equal(llm.lane, tool.lane);
+  assert.ok(llm.start < tool.start && tool.end < llm.end); // the view must put them on separate rows
+  assert.ok(m.lanes.some((l) => l.id === 'agent:Triage') && m.lanes.some((l) => l.id === 'agent:Billing'));
+  assert.deepEqual(m.arrows.map((a) => `${a.kind}:${a.from}->${a.to}`), ['handoff:agent:Triage->agent:Billing']);
+});
+
+// ── nodeStates: the map at the cursor ─────────────────────────────────
+
+const sev = (seq, event_type, extra = {}) => ({ sequence_num: seq, timestamp: 100 + seq, event_type, ...extra });
+
+test('nodeStates: a step is running between its start and end, then done', () => {
+  const events = [
+    sev(0, 'workflow_start'),
+    sev(1, 'step_start', { node_id: 'step:research' }),
+    sev(2, 'step_end', { node_id: 'step:research', data: { status: 'completed' } }),
+    sev(3, 'step_start', { node_id: 'step:draft' }),
+  ];
+  const nodes = [{ id: 'start', kind: 'start' }, { id: 'step:research' }, { id: 'step:draft' }, { id: 'end', kind: 'end' }];
+  const at = (i) => Object.fromEntries([...core.nodeStates(events, i, nodes)].map(([k, v]) => [k, v.state]));
+  assert.deepEqual(at(1), { 'step:research': 'running', start: 'done' });
+  assert.deepEqual(at(2), { 'step:research': 'done', start: 'done' });
+  assert.deepEqual(at(3), { 'step:research': 'done', 'step:draft': 'running', start: 'done' });
+  assert.equal(core.nodeStates(events, -1, nodes).size, 0, 'nothing is reached before the first step');
+});
+
+test('nodeStates: end node is reached when the run ends; failed and skipped come from status', () => {
+  const events = [
+    sev(0, 'step_start', { node_id: 'step:a' }),
+    sev(1, 'step_end', { node_id: 'step:a', data: { status: 'failed' } }),
+    sev(2, 'step_start', { node_id: 'step:b' }),
+    sev(3, 'step_end', { node_id: 'step:b', data: { status: 'skipped' } }),
+    sev(4, 'workflow_end'),
+  ];
+  const st = core.nodeStates(events, Infinity, [{ id: 'end', kind: 'end' }]);
+  assert.equal(st.get('step:a').state, 'failed');
+  assert.equal(st.get('step:b').state, 'skipped');
+  assert.equal(st.get('end').state, 'done');
+});
+
+test('nodeStates: runs count only on the node an end event belongs to', () => {
+  const events = [
+    sev(0, 'task_start', { node_id: 'task:research', agent_name: 'Researcher' }),
+    sev(1, 'agent_start', { agent_name: 'Researcher' }),
+    sev(2, 'agent_end', { agent_name: 'Researcher' }),
+    sev(3, 'task_end', { node_id: 'task:research', agent_name: 'Researcher', data: { status: 'completed' } }),
+    sev(4, 'step_start', { node_id: 'step:loop' }),
+    sev(5, 'step_end', { node_id: 'step:loop' }),
+    sev(6, 'step_start', { node_id: 'step:loop' }),
+    sev(7, 'step_end', { node_id: 'step:loop' }),
+  ];
+  const st = core.nodeStates(events);
+  assert.equal(st.get('agent:Researcher').runs, 1, 'task_end must not count as another agent run');
+  assert.equal(st.get('task:research').runs, 1);
+  assert.equal(st.get('step:loop').runs, 2);
+  assert.equal(st.get('agent:Researcher').state, 'done');
+});
+
+test('nodeStates: a recorded flow fixture ends with every visited node done or failed', () => {
+  const { events, graph } = load('flow_parallel_loop');
+  const m = buildModel(events, graph);
+  const st = core.nodeStates(m.events, Infinity, graph.nodes);
+  assert.ok(st.size > 0);
+  for (const [id, v] of st) assert.notEqual(v.state, 'running', `${id} still running after the run ended`);
+});
+
+// ── unnamed agents (Agent(instructions=...), agent_name null) ────────────
+
+const unnamedRun = (newIds) => [
+  { sequence_num: 0, timestamp: 1, event_type: 'session_start', agent_name: null },
+  { sequence_num: 1, timestamp: 2, event_type: 'agent_start', agent_name: null, node_id: newIds ? 'agent:Agent' : null },
+  { sequence_num: 2, timestamp: 3, event_type: 'llm_request', agent_name: null, node_id: newIds ? 'agent:Agent' : null },
+  { sequence_num: 3, timestamp: 4, event_type: 'llm_response', agent_name: null, node_id: newIds ? 'agent:Agent' : null },
+  { sequence_num: 4, timestamp: 5, event_type: 'tool_call_start', agent_name: null, node_id: newIds ? 'tool:Agent/search' : 'tool:None/search', data: { tool_name: 'search' } },
+  { sequence_num: 5, timestamp: 6, event_type: 'tool_call_end', agent_name: null, node_id: newIds ? 'tool:Agent/search' : 'tool:None/search', data: { tool_name: 'search' } },
+  { sequence_num: 6, timestamp: 7, event_type: 'agent_end', agent_name: null, node_id: newIds ? 'agent:Agent' : null, data: newIds ? { status: 'completed' } : {} },
+  { sequence_num: 7, timestamp: 8, event_type: 'session_end', agent_name: null },
+];
+
+for (const newIds of [true, false]) {
+  test(`unnamed agent is mapped as "Agent" (${newIds ? 'new' : '4.7.19'} trace ids)`, () => {
+    const g = deriveGraph(unnamedRun(newIds));
+    assert.deepEqual(g.nodes.map((n) => [n.id, n.label]), [['agent:Agent', 'Agent'], ['tool:Agent/search', 'search']]);
+    assert.deepEqual(g.edges.map((e) => `${e.source}->${e.target}:${e.kind}`), ['agent:Agent->tool:Agent/search:uses']);
+    const st = core.nodeStates(unnamedRun(newIds), Infinity, g.nodes);
+    assert.equal(st.get('agent:Agent').state, 'done');
+    assert.equal(st.get('tool:Agent/search').state, 'done');
+    assert.ok(![...st.keys()].some((k) => k.includes('None')), 'no tool:None ids leak into the map');
+  });
+}
+
+test('a failed unnamed agent run is red on the map', () => {
+  const evs = unnamedRun(true);
+  evs[6] = { ...evs[6], data: { status: 'failed' } };
+  assert.equal(core.nodeStates(evs, Infinity, deriveGraph(evs).nodes).get('agent:Agent').state, 'failed');
+});
+
+test('unnamed agents do not reappear "outside" a recorded team graph', () => {
+  const graph = { schema: 'praisonai.graph/1', kind: 'team', nodes: [
+    { id: 'start:begin', kind: 'start', label: 'Brief' }, { id: 'task:t', kind: 'task', label: 't' }, { id: 'end:done', kind: 'end', label: 'Delivered' }],
+  edges: [{ source: 'start:begin', target: 'task:t', kind: 'next' }, { source: 'task:t', target: 'end:done', kind: 'next' }] };
+  const og = core.observedGraph(graph, unnamedRun(true));
+  assert.deepEqual(og.nodes.map((n) => n.id), ['start:begin', 'task:t', 'end:done']);
+  assert.deepEqual(og.outside, []);
+});
+
+test('named agents are unchanged', () => {
+  const evs = unnamedRun(true).map((e) => ({ ...e, agent_name: e.agent_name === null && e.event_type !== 'session_start' && e.event_type !== 'session_end' ? 'Writer' : e.agent_name, node_id: e.node_id && e.node_id.replace('Agent', 'Writer') }));
+  assert.deepEqual(deriveGraph(evs).nodes.map((n) => n.id), ['agent:Writer', 'tool:Writer/search']);
+});
+
+test('an unnamed agent is narrated as "Agent", not "The run"', () => {
+  const evs = unnamedRun(true);
+  assert.equal(narrate(evs[1]), 'Agent started.');
+  assert.equal(narrate(evs[7]).startsWith('Recording'), true);
+});

tests/unit/test_approvals_ui_backend.py

@@ -0,0 +1,235 @@
+"""_UIStoreBackend waits for a human decision (contract v1 §5, approvals).
+
+Before: request_approval_sync returned ``approved=False, "Awaiting UI
+approval"`` immediately, so a tool needing approval was always denied and the
+UI's Approve button did nothing for the agent; ``request.approval_id`` and
+``modified_args`` were dropped.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+
+import pytest
+from starlette.applications import Starlette
+from starlette.testclient import TestClient
+
+protocols = pytest.importorskip("praisonaiagents.approval.protocols")
+ApprovalRequest = protocols.ApprovalRequest
+
+
+def _request(approval_id: str = "appr-1", **kw) -> "ApprovalRequest":
+    return ApprovalRequest(
+        tool_name=kw.pop("tool_name", "write_file"),
+        arguments=kw.pop("arguments", {"path": "draft.md"}),
+        risk_level=kw.pop("risk_level", "high"),
+        agent_name=kw.pop("agent_name", "Writer"),
+        approval_id=approval_id,
+        **kw,
+    )
+
+
+@pytest.fixture()
+def store():
+    from praisonaiui.features.approvals import SimpleApprovalManager
+
+    return SimpleApprovalManager()
+
+
+@pytest.fixture()
+def backend(store):
+    from praisonaiui.features.approvals import _UIStoreBackend
+
+    return _UIStoreBackend(store, timeout=5.0)
+
+
+def _wait_pending(store, approval_id: str, timeout: float = 3.0) -> dict:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        for entry in store.list_pending():
+            if entry["id"] == approval_id:
+                return entry
+        time.sleep(0.01)
+    raise AssertionError(f"{approval_id} never became pending")
+
+
+def _in_thread(fn, *args):
+    box = {}
+
+    def run():
+        box["result"] = fn(*args)
+
+    t = threading.Thread(target=run, daemon=True)
+    t.start()
+    return t, box
+
+
+def test_sync_blocks_until_approved_with_modified_args(store, backend):
+    t, box = _in_thread(backend.request_approval_sync, _request("appr-1"))
+    entry = _wait_pending(store, "appr-1")  # honours request.approval_id
+    assert entry["tool_name"] == "write_file" and entry["agent_name"] == "Writer"
+    time.sleep(0.1)
+    assert t.is_alive(), "backend must block while the decision is pending"
+    store.approve("appr-1", reason="Use docs/", modified_args={"path": "docs/draft.md"})
+    t.join(timeout=3)
+    assert not t.is_alive()
+    decision = box["result"]
+    assert decision.approved is True
+    assert decision.modified_args == {"path": "docs/draft.md"}
+    assert decision.reason == "Use docs/"
+
+
+def test_sync_deny_resolves_with_reason(store, backend):
+    t, box = _in_thread(backend.request_approval_sync, _request("appr-2"))
+    _wait_pending(store, "appr-2")
+    store.deny("appr-2", reason="Not today")
+    t.join(timeout=3)
+    assert box["result"].approved is False
+    assert box["result"].reason == "Not today"
+
+
+def test_sync_timeout_denies_and_clears_queue(store):
+    from praisonaiui.features.approvals import _UIStoreBackend
+
+    backend = _UIStoreBackend(store, timeout=0.2)
+    started = time.monotonic()
+    decision = backend.request_approval_sync(_request("appr-3"))
+    assert time.monotonic() - started >= 0.2
+    assert decision.approved is False
+    assert decision.approver == "timeout"
+    assert store.list_pending() == []
+    assert store.get("appr-3")["status"] == "denied"
+
+
+def test_per_id_isolation(store, backend):
+    t1, b1 = _in_thread(backend.request_approval_sync, _request("a"))
+    t2, b2 = _in_thread(backend.request_approval_sync, _request("b"))
+    _wait_pending(store, "a")
+    _wait_pending(store, "b")
+    store.approve("b")
+    t2.join(timeout=3)
+    assert b2["result"].approved is True
+    assert t1.is_alive(), "deciding b must not release a"
+    store.deny("a")
+    t1.join(timeout=3)
+    assert b1["result"].approved is False
+
+
+def test_async_waits_without_blocking_the_loop(store, backend):
+    async def main():
+        task = asyncio.create_task(backend.request_approval(_request("appr-4")))
+        ticks = 0
+        while not store.list_pending():
+            ticks += 1
+            await asyncio.sleep(0.01)
+        # the loop keeps running while waiting
+        for _ in range(5):
+            ticks += 1
+            await asyncio.sleep(0.01)
+        assert not task.done()
+        # decision arrives from another thread (the server handling POST /approve)
+        threading.Timer(0.05, lambda: store.approve("appr-4", modified_args={"x": 1})).start()
+        decision = await asyncio.wait_for(task, 3)
+        return decision, ticks
+
+    decision, ticks = asyncio.run(main())
+    assert decision.approved is True
+    assert decision.modified_args == {"x": 1}
+    assert ticks >= 5
+
+
+def test_async_decision_from_same_loop(store, backend):
+    async def main():
+        task = asyncio.create_task(backend.request_approval(_request("appr-5")))
+        while not store.list_pending():
+            await asyncio.sleep(0.01)
+        store.approve("appr-5")
+        return await asyncio.wait_for(task, 3)
+
+    assert asyncio.run(main()).approved is True
+
+
+def test_async_timeout_denies(store):
+    from praisonaiui.features.approvals import _UIStoreBackend
+
+    backend = _UIStoreBackend(store, timeout=0.15)
+    decision = asyncio.run(backend.request_approval(_request("appr-6")))
+    assert decision.approved is False
+    assert store.get("appr-6")["status"] == "denied"
+
+
+def test_async_cancel_by_registry_wait_for_expires_entry(store, backend):
+    async def main():
+        with pytest.raises(asyncio.TimeoutError):
+            await asyncio.wait_for(backend.request_approval(_request("appr-7")), 0.1)
+
+    asyncio.run(main())
+    assert store.list_pending() == []
+    assert store.get("appr-7")["status"] == "denied"
+
+
+def test_sync_call_on_event_loop_thread_fails_closed_fast(store, backend):
+    async def main():
+        started = time.monotonic()
+        decision = backend.request_approval_sync(_request("appr-8"))
+        return decision, time.monotonic() - started
+
+    decision, elapsed = asyncio.run(main())
+    assert decision.approved is False
+    assert elapsed < 1.0
+    assert store.list_pending() == []
+
+
+def test_auto_policy_still_resolves_immediately(store, backend):
+    store.update_policies({"auto_approve_tools": ["write_file"]})
+    decision = backend.request_approval_sync(_request("appr-9"))
+    assert decision.approved is True
+    assert decision.approver == "auto-policy"
+
+
+def test_approve_endpoint_passes_modified_args(store, backend, monkeypatch):
+    from praisonaiui.features import approvals
+
+    monkeypatch.setattr(approvals, "_approval_manager", store)
+    client = TestClient(Starlette(routes=approvals.ApprovalsFeature().routes()))
+    t, box = _in_thread(backend.request_approval_sync, _request("appr-10"))
+    _wait_pending(store, "appr-10")
+    assert client.get("/api/approvals/appr-10").json()["arguments"] == {"path": "draft.md"}
+    r = client.post("/api/approvals/appr-10/approve", json={"modified_args": {"path": "docs/x.md"}, "reason": "ok"})
+    assert r.status_code == 200
+    assert r.json()["modified_args"] == {"path": "docs/x.md"}
+    t.join(timeout=3)
+    assert box["result"].approved is True
+    assert box["result"].modified_args == {"path": "docs/x.md"}
+
+
+def test_approve_endpoint_rejects_non_object_modified_args(store, monkeypatch):
+    from praisonaiui.features import approvals
+
+    monkeypatch.setattr(approvals, "_approval_manager", store)
+    store.request_approval({"id": "z", "tool_name": "t", "risk_level": "high"})
+    client = TestClient(Starlette(routes=approvals.ApprovalsFeature().routes()))
+    r = client.post("/api/approvals/z/approve", json={"modified_args": [1, 2]})
+    assert r.status_code == 400
+    assert store.get("z")["status"] == "pending"
+    # plain approve without modified_args still works (and keeps old managers working)
+    assert client.post("/api/approvals/z/approve", json={}).status_code == 200
+
+
+def test_sdk_manager_approve_forwards_modified_args():
+    pytest.importorskip("praisonaiagents.approval")
+    from praisonaiagents.approval import get_approval_registry
+
+    from praisonaiui.features.approvals import SDKApprovalManager
+
+    registry = get_approval_registry()
+    previous = registry.get_backend()
+    try:
+        mgr = SDKApprovalManager()
+        mgr._simple.request_approval({"id": "s1", "tool_name": "t", "risk_level": "high"})
+        entry = mgr.approve("s1", modified_args={"k": "v"})
+        assert entry["modified_args"] == {"k": "v"}
+    finally:
+        registry.set_backend(previous)

tests/unit/test_chat_full_bleed_layout.py

@@ -0,0 +1,54 @@
+"""Regression tests for #322 — Chat must fill the dashboard main column.
+
+Chat pages declare ``layout: "full-bleed"``; ``selectPage()`` then adds
+``db-fill`` to ``#db-main-content`` and skips the duplicate page header, and
+``.chat-root`` sizes from flex allocation instead of ``calc(100vh - 140px)``.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+PLUGINS = (
+    Path(__file__).resolve().parents[2]
+    / "src" / "praisonaiui" / "templates" / "frontend" / "plugins"
+)
+
+
+def _select_page_body() -> str:
+    src = (PLUGINS / "dashboard.js").read_text(encoding="utf-8")
+    m = re.search(r"async function selectPage\(pageId\)\s*\{(.*?)^}", src, re.DOTALL | re.MULTILINE)
+    assert m
+    return m.group(1)
+
+
+def test_chat_pages_declare_full_bleed():
+    from starlette.testclient import TestClient
+
+    from praisonaiui.server import create_app, reset_state
+
+    reset_state()  # isolate from page whitelists set by other tests
+    pages = {p["id"]: p for p in TestClient(create_app()).get("/api/pages").json()["pages"]}
+    for pid in ("chat", "chat-canvas"):
+        assert pages[pid].get("layout") == "full-bleed"
+    assert pages["overview"].get("layout") is None
+
+
+def test_select_page_toggles_fill_and_skips_header():
+    body = _select_page_body()
+    assert "page.layout === 'full-bleed'" in body
+    assert "classList.toggle('db-fill'" in body
+    assert re.search(r"showPageHeader = .*&& !fullBleed", body)
+
+
+def test_fill_css_defined():
+    src = (PLUGINS / "dashboard.js").read_text(encoding="utf-8")
+    assert ".db-main.db-fill > #db-page-content" in src
+
+
+def test_chat_root_fills_column_in_fill_mode():
+    chat = (PLUGINS / "views" / "chat.js").read_text(encoding="utf-8")
+    assert re.search(r"\.db-fill \.chat-root \{[^}]*flex:1;[^}]*min-height:0", chat)
+    canvas = (PLUGINS / "views" / "chat-canvas.js").read_text(encoding="utf-8")
+    assert ".db-fill .chat-canvas-root" in canvas

tests/unit/test_chat_session_rail_search.py

@@ -0,0 +1,31 @@
+"""Tests for the in-rail session search in the chat view (issue #324).
+
+The chat sidebar must expose a search input that filters the already
+fetched session list client-side, without refetching from the API.
+"""
+
+from pathlib import Path
+
+CHAT = Path("src/praisonaiui/templates/frontend/plugins/views/chat.js")
+
+
+class TestChatSessionRailSearch:
+    def test_search_input_rendered_in_rail(self):
+        src = CHAT.read_text()
+        assert 'id="chat-session-search"' in src
+        assert src.index('id="chat-session-search"') < src.index('id="chat-sessions-list"')
+
+    def test_input_wired_to_client_side_render(self):
+        src = CHAT.read_text()
+        assert "sessionSearch.addEventListener('input', renderSessionList)" in src
+
+    def test_load_sessions_caches_and_delegates_render(self):
+        src = CHAT.read_text()
+        assert "allSessions = Array.isArray(fetched) ? fetched : [];" in src
+        body = src.split("async function loadSessions()", 1)[1].split("\n}\n", 1)[0]
+        assert "renderSessionList();" in body
+
+    def test_filter_matches_title_and_id_fields(self):
+        src = CHAT.read_text()
+        assert "function _sessionMatches(s, q)" in src
+        assert "No matching sessions" in src

tests/unit/test_chat_session_rename.py

@@ -0,0 +1,49 @@
+"""Issue #331 — rename a session from the chat rail via the existing PATCH route."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from starlette.applications import Starlette
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+import praisonaiui.server as server
+from praisonaiui.datastore import MemoryDataStore
+
+CHAT = Path("src/praisonaiui/templates/frontend/plugins/views/chat.js")
+
+
+def _client(monkeypatch):
+    ds = MemoryDataStore()
+    monkeypatch.setattr(server, "_datastore", ds)
+    app = Starlette(routes=[Route("/sessions/{session_id}", server.patch_session, methods=["PATCH"])])
+    sid = asyncio.run(ds.create_session())["id"]
+    return TestClient(app), ds, sid
+
+
+def test_patch_renames_and_trims(monkeypatch):
+    client, ds, sid = _client(monkeypatch)
+    r = client.patch(f"/sessions/{sid}", json={"title": "  My chat  "})
+    assert r.status_code == 200
+    assert asyncio.run(ds.get_session(sid))["title"] == "My chat"
+
+
+def test_patch_rejects_blank_or_non_string_title(monkeypatch):
+    client, _, sid = _client(monkeypatch)
+    assert client.patch(f"/sessions/{sid}", json={"title": "   "}).status_code == 400
+    assert client.patch(f"/sessions/{sid}", json={"title": 123}).status_code == 400
+
+
+def test_patch_unknown_session_404(monkeypatch):
+    client, _, _ = _client(monkeypatch)
+    assert client.patch("/sessions/nope", json={"title": "x"}).status_code == 404
+
+
+def test_rail_has_rename_button_wired_to_patch():
+    src = CHAT.read_text()
+    assert "async function renameSession(sessionId, currentTitle)" in src
+    assert "method: 'PATCH'" in src
+    assert "renameSession(id, title)" in src
+    assert "e.stopPropagation()" in src

tests/unit/test_jobs_open_session.py

@@ -0,0 +1,31 @@
+"""Issue #323 — Jobs rows link to their chat session when ``session_id`` is set.
+
+Source-parsing test, mirroring ``test_session_search_dashboard.py``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+JOBS_JS = (
+    Path(__file__).resolve().parents[2]
+    / "src" / "praisonaiui" / "templates" / "frontend" / "plugins" / "jobs.js"
+)
+
+
+def _src() -> str:
+    return JOBS_JS.read_text(encoding="utf-8")
+
+
+def test_open_session_button_only_when_session_id():
+    src = _src()
+    assert "job.session_id ? `<button" in src
+    assert 'data-session-id="${escapeAttr(job.session_id)}"' in src
+
+
+def test_open_session_reuses_session_select_event():
+    src = _src()
+    assert "function openJobSession(sessionId)" in src
+    assert "selectPage('chat')" in src
+    assert "'aiui:session-select'" in src
+    assert "window.aiuiOpenJobSession = openJobSession;" in src

tests/unit/test_replay_embed.py

@@ -0,0 +1,166 @@
+"""create_replay_app(): the Replay view mounted inside another app, with an optional Run box."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import threading
+import time
+from pathlib import Path
+
+import pytest
+from starlette.applications import Starlette
+from starlette.routing import Mount
+from starlette.testclient import TestClient
+
+FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "replay"
+
+
+@pytest.fixture()
+def traces(tmp_path, monkeypatch):
+    d = tmp_path / "traces"
+    d.mkdir()
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(d))
+    monkeypatch.delenv("PRAISON_HOME", raising=False)
+    return d
+
+
+def _host(sub) -> TestClient:
+    """A host app with the replay app mounted at /replay, like app.mount() in FastAPI."""
+    return TestClient(Starlette(routes=[Mount("/replay", app=sub)]))
+
+
+def _cfg(page: str) -> dict:
+    line = next(l for l in page.splitlines() if l.startswith("render("))
+    return json.loads(line[line.index(",") + 1 : line.rindex(")")].strip())
+
+
+def test_page_mounts_the_view_relative_to_the_mount(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    c = _host(create_replay_app())
+    r = c.get("/replay/")
+    assert r.status_code == 200
+    assert 'from "/replay/replay.js"' in r.text
+    cfg = _cfg(r.text)
+    assert cfg == {"base": "/replay", "approve": False}  # no run list pin, no Run box
+    assert "aiui" not in r.text.lower()  # no dashboard around it
+    for name in ("replay.js", "replay-core.js"):
+        js = c.get(f"/replay/{name}")
+        assert js.status_code == 200 and js.headers["content-type"].startswith("text/javascript")
+
+
+def test_page_pins_a_valid_run_and_ignores_a_bad_one(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    c = _host(create_replay_app())
+    assert _cfg(c.get("/replay/?run=run-abc").text)["run"] == "run-abc"
+    page = c.get("/replay/?run=../../etc/passwd").text
+    assert "run" not in _cfg(page) and "passwd" not in page
+
+
+def test_api_routes_answer_under_the_mount(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    shutil.copy(FIXTURES / "team_handoff.jsonl", traces / "team_handoff.jsonl")
+    c = _host(create_replay_app())
+    rows = c.get("/replay/api/replay/runs").json()
+    assert [r["run_id"] for r in rows] == ["team_handoff"]
+    assert c.get("/replay/api/replay/runs/team_handoff/events").json()["events"]
+
+
+def test_events_wait_param_answers_a_missing_run_without_404(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    c = _host(create_replay_app())
+    assert c.get("/replay/api/replay/runs/run-later/events").status_code == 404
+    r = c.get("/replay/api/replay/runs/run-later/events?wait=1")
+    assert r.status_code == 200 and r.json() == {"events": [], "graph": None, "run": None}
+
+
+def test_no_run_route_without_a_runner(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    c = _host(create_replay_app())
+    assert c.post("/replay/api/replay/run", json={"input": "x"}).status_code in (404, 405)
+
+
+def test_run_box_calls_the_runner_with_a_new_run_id(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    calls = []
+
+    def runner(text, run_id):
+        (traces / f"{run_id}.jsonl").write_text(json.dumps({"event_type": "session_start", "sequence_num": 0, "timestamp": time.time()}) + "\n")
+        calls.append((text, run_id))
+
+    c = _host(create_replay_app(runner, input="solar sails", placeholder="Topic"))
+    cfg = _cfg(c.get("/replay/").text)
+    assert cfg["runner"] == {"input": "solar sails", "placeholder": "Topic", "ask": True}
+    r = c.post("/replay/api/replay/run", json={"input": "comets"})
+    assert r.status_code == 200
+    run_id = r.json()["run_id"]
+    assert (traces / f"{run_id}.jsonl").is_file(), "answers once the trace exists"
+    for _ in range(100):
+        if calls:
+            break
+        time.sleep(0.01)
+    assert calls == [("comets", run_id)]
+    assert run_id.startswith("run-") and len(run_id) == 16
+
+
+def test_run_box_without_input_box(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    cfg = _cfg(_host(create_replay_app(lambda t, r: None, input=None)).get("/replay/").text)
+    assert cfg["runner"]["ask"] is False
+
+
+def test_run_rejects_non_json_bad_input_and_a_second_run(traces):
+    from praisonaiui.features.replay import MAX_RUN_INPUT, create_replay_app
+
+    gate = threading.Event()
+    c = _host(create_replay_app(lambda text, run_id: gate.wait(5)))
+    assert c.post("/replay/api/replay/run", data="input=x", headers={"content-type": "application/x-www-form-urlencoded"}).status_code == 415
+    assert c.post("/replay/api/replay/run", content="input=x", headers={"content-type": "text/plain"}).status_code == 415
+    assert c.post("/replay/api/replay/run", json={"input": 3}).status_code == 400
+    assert c.post("/replay/api/replay/run", json={"input": "x" * (MAX_RUN_INPUT + 1)}).status_code == 400
+    assert c.post("/replay/api/replay/run", json={"input": "a"}).status_code == 200
+    busy = c.post("/replay/api/replay/run", json={"input": "b"})
+    assert busy.status_code == 409 and "already" in busy.json()["error"]
+    gate.set()
+    for _ in range(100):  # the lock is released when the runner returns
+        r = c.post("/replay/api/replay/run", json={"input": "c"})
+        if r.status_code == 200:
+            break
+        time.sleep(0.02)
+    assert r.status_code == 200
+
+
+def test_a_failing_runner_frees_the_run_box(traces, caplog):
+    from praisonaiui.features.replay import create_replay_app
+
+    def boom(text, run_id):
+        raise RuntimeError("no key")
+
+    c = _host(create_replay_app(boom))
+    assert c.post("/replay/api/replay/run", json={"input": ""}).status_code == 200
+    for _ in range(100):
+        r = c.post("/replay/api/replay/run", json={"input": ""})
+        if r.status_code == 200:
+            break
+        time.sleep(0.02)
+    assert r.status_code == 200
+
+
+def test_async_runner_is_awaited(traces):
+    from praisonaiui.features.replay import create_replay_app
+
+    done = threading.Event()
+
+    async def runner(text, run_id):
+        done.set()
+
+    c = _host(create_replay_app(runner))
+    assert c.post("/replay/api/replay/run", json={"input": ""}).status_code == 200
+    assert done.wait(3)

tests/unit/test_replay_feature.py

@@ -0,0 +1,439 @@
+"""PraisonAI Replay feature: runs listing, events, SSE tail, safety (contract v1 §1, §5)."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import threading
+import time
+from pathlib import Path
+
+import pytest
+from starlette.applications import Starlette
+from starlette.testclient import TestClient
+
+FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "replay"
+NAMES = ("team_handoff", "flow_parallel_loop", "legacy_v10")
+
+
+def _lines(name: str) -> list[str]:
+    return (FIXTURES / f"{name}.jsonl").read_text(encoding="utf-8").splitlines(keepends=True)
+
+
+@pytest.fixture()
+def traces(tmp_path, monkeypatch):
+    d = tmp_path / "traces"
+    d.mkdir()
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(d))
+    monkeypatch.delenv("PRAISON_HOME", raising=False)
+    return d
+
+
+@pytest.fixture()
+def isolated_server(tmp_path, monkeypatch):
+    """create_app() writes a config store; keep it out of the developer's home."""
+    monkeypatch.setenv("AIUI_DATA_DIR", str(tmp_path / "aiui-data"))
+    monkeypatch.setenv("PRAISONAI_HOME", str(tmp_path / "praisonai-home"))
+
+
+@pytest.fixture()
+def feature():
+    from praisonaiui.features.replay import ReplayFeature
+
+    f = ReplayFeature()
+    f.poll_interval = 0.02
+    f.ping_interval = 0.15
+    f.quiet_period = 0.3
+    return f
+
+
+@pytest.fixture()
+def client(feature):
+    app = Starlette(routes=feature.routes())
+    return TestClient(app)
+
+
+def _copy_all(d: Path) -> None:
+    for name in NAMES:
+        dst = d / f"{name}.jsonl"
+        shutil.copy(FIXTURES / f"{name}.jsonl", dst)
+
+
+# ── traces dir resolution ────────────────────────────────────────────
+
+
+def test_traces_dir_precedence(tmp_path, monkeypatch):
+    from praisonaiui.features import _trace_jsonl as tj
+
+    monkeypatch.delenv("PRAISONAI_TRACES_DIR", raising=False)
+    monkeypatch.delenv("PRAISON_HOME", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
+    assert tj.traces_dir() == tmp_path / "home" / ".praison" / "traces"
+    monkeypatch.setenv("PRAISON_HOME", str(tmp_path / "ph"))
+    assert tj.traces_dir() == tmp_path / "ph" / "traces"
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(tmp_path / "explicit"))
+    assert tj.traces_dir() == tmp_path / "explicit"
+
+
+# ── /api/replay/runs ─────────────────────────────────────────────────
+
+
+def test_runs_lists_fixtures_newest_first(traces, client):
+    _copy_all(traces)
+    r = client.get("/api/replay/runs")
+    assert r.status_code == 200
+    rows = r.json()
+    assert isinstance(rows, list)
+    by_id = {row["run_id"]: row for row in rows}
+    assert set(by_id) == set(NAMES)
+    # newest first by started_at
+    started = [row["started_at"] for row in rows]
+    assert started == sorted(started, reverse=True)
+
+    team = by_id["team_handoff"]
+    assert team["session_id"] == "sess-team-01"
+    assert team["kind"] == "team"
+    assert team["name"] == "Solar sail brief"
+    assert team["status"] == "completed"
+    assert team["live"] is False
+    assert team["events"] == 36
+    assert team["agents"] == ["Manager", "Researcher", "Writer"]
+    assert team["cost_usd"] == pytest.approx(0.006741, abs=1e-9)
+    assert team["ended_at"] == pytest.approx(1767225612.25)
+    assert team["path"].endswith("team_handoff.jsonl")
+    assert team["event_run_id"] == "team-handoff-01"
+
+    legacy = by_id["legacy_v10"]  # schema 1.0: no workflow_start, still listed
+    assert legacy["kind"] == "session"
+    assert legacy["status"] == "completed"
+    assert legacy["schema_version"] == "1.0"
+    assert legacy["agents"] == ["Assistant", "Checker"]
+    assert legacy["events"] == 16
+
+
+def test_runs_empty_or_missing_dir(tmp_path, monkeypatch, client):
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(tmp_path / "nope"))
+    r = client.get("/api/replay/runs")
+    assert r.status_code == 200
+    assert r.json() == []
+
+
+def test_run_without_end_marker_is_live(traces, client):
+    lines = _lines("team_handoff")
+    (traces / "half.jsonl").write_text("".join(lines[:20]), encoding="utf-8")
+    row = client.get("/api/replay/runs").json()[0]
+    assert row["run_id"] == "half"
+    assert row["live"] is True
+    assert row["status"] == "running"
+    assert "ended_at" not in row
+
+
+def test_ignores_non_jsonl_and_unsafe_names(traces, client):
+    _copy_all(traces)
+    (traces / "notes.txt").write_text("x", encoding="utf-8")
+    (traces / "bad name.jsonl").write_text(_lines("legacy_v10")[0], encoding="utf-8")
+    ids = {row["run_id"] for row in client.get("/api/replay/runs").json()}
+    assert ids == set(NAMES)
+
+
+# ── /api/replay/runs/{id}/events ─────────────────────────────────────
+
+
+def test_events_and_graph(traces, client):
+    _copy_all(traces)
+    data = client.get("/api/replay/runs/team_handoff/events").json()
+    assert len(data["events"]) == 36
+    assert data["graph"]["schema"] == "praisonai.graph/1"
+    assert data["graph"]["process"] == "hierarchical"
+    assert data["run"]["run_id"] == "team_handoff"
+    legacy = client.get("/api/replay/runs/legacy_v10/events").json()
+    assert legacy["graph"] is None
+    assert len(legacy["events"]) == 16
+
+
+def test_events_after_seq(traces, client):
+    _copy_all(traces)
+    data = client.get("/api/replay/runs/team_handoff/events?after_seq=30").json()
+    assert [e["sequence_num"] for e in data["events"]] == [31, 32, 33, 34, 35]
+    # graph still comes from the (earlier) workflow_start
+    assert data["graph"] is not None
+    assert client.get("/api/replay/runs/team_handoff/events?after_seq=-1").json()["events"][0]["sequence_num"] == 0
+    assert client.get("/api/replay/runs/team_handoff/events?after_seq=abc").status_code == 400
+
+
+def test_unknown_event_types_and_fields_pass_through(traces, client):
+    _copy_all(traces)
+    events = client.get("/api/replay/runs/flow_parallel_loop/events").json()["events"]
+    odd = [e for e in events if e["event_type"] == "context_rebalance"]
+    assert len(odd) == 1
+    assert odd[0]["future_field"] == {"x": 1}
+
+
+def test_partial_last_line_ignored_until_complete(traces, client):
+    lines = _lines("legacy_v10")
+    path = traces / "growing.jsonl"
+    last = lines[-1]
+    path.write_text("".join(lines[:-1]) + last[:25], encoding="utf-8")
+    first = client.get("/api/replay/runs/growing/events").json()["events"]
+    assert len(first) == 15  # half-written session_end is not surfaced
+    assert first[-1]["event_type"] == "agent_end"
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(last[25:])
+    second = client.get("/api/replay/runs/growing/events").json()["events"]
+    assert len(second) == 16
+    assert second[-1]["event_type"] == "session_end"
+
+
+def test_complete_last_line_without_newline_is_read(traces, client):
+    text = "".join(_lines("legacy_v10")).rstrip("\n")
+    (traces / "nonl.jsonl").write_text(text, encoding="utf-8")
+    events = client.get("/api/replay/runs/nonl/events").json()["events"]
+    assert len(events) == 16
+
+
+def test_garbage_lines_are_skipped(traces, client):
+    lines = _lines("legacy_v10")
+    (traces / "dirty.jsonl").write_text(lines[0] + "not json\n[1,2]\n\n" + "".join(lines[1:]), encoding="utf-8")
+    assert len(client.get("/api/replay/runs/dirty/events").json()["events"]) == 16
+
+
+# ── safety ───────────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "run_id",
+    ["..", ".", "a b", "a;b", "%2e%2e", "..%2Fsecret", "x%00y", "ü"],
+)
+def test_path_traversal_ids_rejected(traces, client, run_id):
+    secret = traces.parent / "secret.jsonl"
+    secret.write_text(_lines("legacy_v10")[0], encoding="utf-8")
+    for suffix in ("events", "stream"):
+        r = client.get(f"/api/replay/runs/{run_id}/{suffix}")
+        assert r.status_code in (400, 404), (run_id, suffix, r.status_code)
+        assert "legacy-sess-10" not in r.text
+
+
+def test_run_path_validation_unit(tmp_path):
+    from praisonaiui.features import _trace_jsonl as tj
+
+    assert tj.run_path("../etc/passwd", tmp_path) is None
+    assert tj.run_path("..", tmp_path) is None
+    assert tj.run_path("a/b", tmp_path) is None
+    assert tj.run_path("ok-run_1.2", tmp_path) == tmp_path / "ok-run_1.2.jsonl"
+
+
+def test_symlink_escaping_dir_is_rejected(traces, client, tmp_path):
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    target = outside / "x.jsonl"
+    target.write_text(_lines("legacy_v10")[0], encoding="utf-8")
+    link = traces / "sneaky.jsonl"
+    try:
+        link.symlink_to(target)
+    except (OSError, NotImplementedError):
+        pytest.skip("symlinks unavailable")
+    assert client.get("/api/replay/runs/sneaky/events").status_code == 400
+
+
+def test_unknown_run_is_404(traces, client):
+    assert client.get("/api/replay/runs/nope/events").status_code == 404
+    assert client.get("/api/replay/runs/nope/stream").status_code == 404
+
+
+# ── SSE stream ───────────────────────────────────────────────────────
+
+
+def _parse_sse(text: str) -> list[tuple[str, str, str | None]]:
+    out = []
+    for block in text.split("\n\n"):
+        if not block.strip():
+            continue
+        name, data, ident = "message", [], None
+        for line in block.split("\n"):
+            if line.startswith("event:"):
+                name = line[6:].strip()
+            elif line.startswith("data:"):
+                data.append(line[5:].strip())
+            elif line.startswith("id:"):
+                ident = line[3:].strip()
+        if data or name != "message":
+            out.append((name, "\n".join(data), ident))
+    return out
+
+
+def test_stream_tails_appended_lines(traces, client, monkeypatch):
+    """Lines written while the stream is open (including one written in two
+    halves) arrive exactly once, in order; the stream ends after session_end."""
+    from praisonaiui.features import _trace_jsonl as tj
+
+    monkeypatch.setattr(tj, "LIVE_WINDOW_S", 8)  # safety net: never hang the suite
+    lines = _lines("team_handoff")
+    path = traces / "live-run.jsonl"
+    path.write_text("".join(lines[:10]), encoding="utf-8")
+
+    def writer():
+        time.sleep(0.15)
+        for i, line in enumerate(lines[10:]):
+            with open(path, "a", encoding="utf-8") as fh:
+                if i == 5:  # a line split across two writes
+                    fh.write(line[:30])
+                    fh.flush()
+                    time.sleep(0.08)
+                    fh.write(line[30:])
+                else:
+                    fh.write(line)
+            time.sleep(0.01)
+
+    t = threading.Thread(target=writer, daemon=True)
+    t.start()
+    started = time.monotonic()
+    with client.stream("GET", "/api/replay/runs/live-run/stream") as r:
+        assert r.status_code == 200
+        assert r.headers["content-type"].startswith("text/event-stream")
+        body = "".join(r.iter_text())
+    elapsed = time.monotonic() - started
+    t.join(timeout=5)
+
+    msgs = _parse_sse(body)
+    ctx = [json.loads(d) for name, d, _ in msgs if name == "ctx"]
+    assert [e["sequence_num"] for e in ctx] == list(range(36))
+    assert [ident for name, _, ident in msgs if name == "ctx"] == [str(i) for i in range(36)]
+    assert msgs[-1][0] == "end"
+    assert any(name == "ping" for name, _, _ in msgs)
+    assert elapsed < 7, "stream should end shortly after session_end + quiet period"
+
+
+def test_stream_after_seq_and_last_event_id(traces, client):
+    shutil.copy(FIXTURES / "legacy_v10.jsonl", traces / "done.jsonl")
+    with client.stream("GET", "/api/replay/runs/done/stream?after_seq=12") as r:
+        body = "".join(r.iter_text())
+    seqs = [json.loads(d)["sequence_num"] for n, d, _ in _parse_sse(body) if n == "ctx"]
+    assert seqs == [13, 14, 15]
+    # reconnect: Last-Event-ID beats an older after_seq in the URL
+    with client.stream("GET", "/api/replay/runs/done/stream?after_seq=2", headers={"Last-Event-ID": "14"}) as r:
+        body = "".join(r.iter_text())
+    seqs = [json.loads(d)["sequence_num"] for n, d, _ in _parse_sse(body) if n == "ctx"]
+    assert seqs == [15]
+
+
+def test_stream_ends_for_stale_unfinished_file(traces, client, monkeypatch):
+    from praisonaiui.features import _trace_jsonl as tj
+
+    monkeypatch.setattr(tj, "LIVE_WINDOW_S", 0.4)
+    (traces / "stale.jsonl").write_text("".join(_lines("team_handoff")[:5]), encoding="utf-8")
+    with client.stream("GET", "/api/replay/runs/stale/stream") as r:
+        body = "".join(r.iter_text())
+    msgs = _parse_sse(body)
+    assert len([m for m in msgs if m[0] == "ctx"]) == 5
+    assert msgs[-1][0] == "end" and "stale" in msgs[-1][1]
+
+
+def test_stream_restarts_when_file_is_truncated(tmp_path):
+    from praisonaiui.features import _trace_jsonl as tj
+
+    path = tmp_path / "r.jsonl"
+    lines = _lines("legacy_v10")
+    path.write_text("".join(lines), encoding="utf-8")
+    tail = tj.TailReader(path)
+    assert len(tail.poll()) == 16
+    path.write_text(lines[0], encoding="utf-8")  # writer restarted the file
+    again = tail.poll()
+    assert len(again) == 1 and again[0]["sequence_num"] == 0
+
+
+# ── registration / entry point ───────────────────────────────────────
+
+
+def test_feature_registered_by_default():
+    from praisonaiui.features import auto_register_defaults, get_feature
+
+    auto_register_defaults()
+    f = get_feature("replay")
+    assert f is not None
+    paths = {r.path for r in f.routes()}
+    assert paths == {
+        "/api/replay/runs",
+        "/api/replay/runs/{run_id}/events",
+        "/api/replay/runs/{run_id}/stream",
+    }
+
+
+def test_replay_page_and_routes_mounted_in_server(traces, isolated_server):
+    import praisonaiui as aiui
+    import praisonaiui.server as server
+
+    _copy_all(traces)
+    server.reset_state()
+    aiui.set_style("dashboard")
+    app = server.create_app()
+    c = TestClient(app)
+    pages = c.get("/api/pages").json()["pages"]
+    page = next((p for p in pages if p["id"] == "replay"), None)
+    assert page is not None
+    assert page["title"] == "Replay"
+    assert page["group"] == "Control"
+    assert page["api_endpoint"] == "/api/replay/runs"
+    assert len(c.get("/api/replay/runs").json()) == 3
+    assert c.get("/plugins/views/replay.js").status_code == 200
+    assert c.get("/plugins/views/replay-core.js").status_code == 200
+
+
+def test_replay_app_whitelists_replay_first(traces, isolated_server):
+    import praisonaiui.server as server
+    from praisonaiui.features.replay import REPLAY_PAGES, configure_replay_app
+
+    server.reset_state()
+    configure_replay_app()
+    try:
+        app = server.create_app()
+        pages = TestClient(app).get("/api/pages").json()["pages"]
+        builtin = [p["id"] for p in pages if p["id"] in REPLAY_PAGES]
+        assert builtin[0] == "replay"
+        assert set(builtin) == set(REPLAY_PAGES)
+        assert "chat" not in {p["id"] for p in pages}
+    finally:
+        server.reset_state()
+
+
+def test_replay_app_module_is_importable_and_documented():
+    import importlib
+
+    src = (Path(__file__).resolve().parents[2] / "src" / "praisonaiui" / "replay_app.py").read_text(encoding="utf-8")
+    assert "aiui run" in src and "/replay?run=" in src
+    import praisonaiui.server as server
+
+    try:
+        importlib.import_module("praisonaiui.replay_app")
+        assert server.get_style() == "dashboard"
+    finally:
+        server.reset_state()
+
+
+def test_cli_list(traces, feature):
+    _copy_all(traces)
+    out = feature._cli_list()
+    assert "team_handoff" in out and "Solar sail brief" in out
+
+
+# ── standalone export helper ─────────────────────────────────────────
+
+
+def test_standalone_html_is_self_contained():
+    from praisonaiui.features.replay import standalone_html
+
+    events = [json.loads(line) for line in _lines("team_handoff")]
+    events[3]["data"]["evil"] = "</script><script>alert(1)</script>"
+    html = standalone_html(events, title="Run <1>")
+    assert html.count("<script") == 3  # data + core + view, nothing injected
+    assert "</script><script>alert" not in html
+    assert "window.__REPLAY_DATA__" in html
+    assert "export function buildModel" in html and "export async function render" in html
+    assert "<title>Run &lt;1&gt;</title>" in html
+    for banned in ("http://", "https://", "cdn"):
+        # SVG namespace URI is a name, not a fetch
+        assert banned not in html.replace("http://www.w3.org/2000/svg", ""), banned
+    # graph is picked up from workflow_start when not passed
+    payload = html.split("window.__REPLAY_DATA__ = ", 1)[1].split(";</script>", 1)[0]
+    data = json.loads(payload)
+    assert data["graph"]["schema"] == "praisonai.graph/1"
+    assert len(data["events"]) == 36

tests/unit/test_replay_view.py

@@ -0,0 +1,149 @@
+"""PraisonAI Replay dashboard view: registration and wiring (source-grep, like test_run_recorder)."""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+FRONTEND = ROOT / "src" / "praisonaiui" / "templates" / "frontend" / "plugins"
+VIEWS = FRONTEND / "views"
+CORE = VIEWS / "replay-core.js"
+VIEW = VIEWS / "replay.js"
+
+
+def test_view_files_exist():
+    assert CORE.exists()
+    assert VIEW.exists()
+
+
+def test_replay_registered_in_builtin_views():
+    source = (FRONTEND / "dashboard.js").read_text(encoding="utf-8")
+    block = source.split("const BUILTIN_VIEWS = {", 1)[1].split("};", 1)[0]
+    assert re.search(r"^\s*replay:\s*'/plugins/views/replay\.js',", block, re.M)
+
+
+def test_dashboard_accepts_hash_deep_links():
+    source = (FRONTEND / "dashboard.js").read_text(encoding="utf-8")
+    assert "location.hash.match(" in source
+    assert "history.replaceState(null, '', `/${hashRoute[1]}" in source
+
+
+def test_core_exports_pure_api():
+    source = CORE.read_text(encoding="utf-8")
+    for fn in (
+        "export function buildModel",
+        "export function narrate",
+        "export function layoutMap",
+        "export function deriveGraph",
+    ):
+        assert fn in source, fn
+    assert "globalThis.PraisonReplayCore = api" in source
+    # pure: no DOM and no network
+    for banned in ("document.", "window.", "fetch(", "EventSource", "localStorage"):
+        assert banned not in source, banned
+
+
+def test_view_exports_render_and_cleanup():
+    source = VIEW.read_text(encoding="utf-8")
+    assert "export async function render" in source
+    assert "export function cleanup" in source
+    assert "abort" in source.lower()
+    assert "es.close()" in source
+
+
+def test_view_uses_contract_endpoints():
+    source = VIEW.read_text(encoding="utf-8")
+    for url in (
+        "/api/replay/runs",
+        "/api/replay/runs/${encodeURIComponent(id)}/events",
+        "/api/replay/runs/${encodeURIComponent(id)}/stream",
+        "/api/approvals/${encodeURIComponent(b.approvalId)}/${action}",
+        "modified_args",
+    ):
+        assert url in source, url
+
+
+def test_no_cdn_or_third_party_assets():
+    for path in (CORE, VIEW):
+        text = path.read_text(encoding="utf-8")
+        stripped = text.replace("http://www.w3.org/2000/svg", "")
+        assert "http://" not in stripped and "https://" not in stripped, path.name
+        assert not re.search(r"cdn[\w-]*\.[a-z]{2,}", stripped.lower()), path.name
+        assert "mermaid" not in stripped.lower(), path.name
+        assert not re.search(r"^\s*import .* from ['\"](?!\./|/plugins/)", text, re.M), path.name
+
+
+def test_palette_and_shapes_follow_contract():
+    core = CORE.read_text(encoding="utf-8")
+    for colour in ("#8B0000", "#0F7287", "#8A5A00", "#3C4A5C"):
+        assert colour in core
+    assert "#189AB4" not in core + VIEW.read_text(encoding="utf-8")
+    for pair in ("agent: 'circle'", "tool: 'rounded'", "human: 'diamond'", "manager: 'square'"):
+        assert pair in core
+
+
+def test_accessibility_hooks_present():
+    view = VIEW.read_text(encoding="utf-8")
+    assert "prefers-reduced-motion" in view
+    assert ":focus-visible" in view
+    assert "aria-live" in view
+    assert "role: 'tablist'" in view and "role: 'tab'" in view and "role: 'tabpanel'" in view
+    assert "aria-current" in view
+    assert "'ArrowLeft'" in view and "'ArrowRight'" in view
+    assert "praisonai replay view agents.yaml" in view
+    assert "with record(" in view
+    assert "Studio" not in view and "__start__" not in view
+
+
+def test_standalone_boot_contract():
+    view = VIEW.read_text(encoding="utf-8")
+    assert "globalThis.__REPLAY_DATA__" in view
+    assert "replay-root" in view
+    assert "globalThis.PraisonReplayCore" in view
+
+
+def test_replay_core_node_suite():
+    """Runs tests/js/replay-core.test.mjs (buildModel, narrate, layoutMap) when Node is present."""
+    node = shutil.which("node")
+    if not node:
+        pytest.skip("node not installed")
+    proc = subprocess.run(
+        [node, "--test", str(ROOT / "tests" / "js" / "replay-core.test.mjs")],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+    assert proc.returncode == 0, proc.stdout[-4000:] + proc.stderr[-2000:]
+    assert re.search(r"# fail 0", proc.stdout)
+
+
+def test_replay_page_uses_own_svg_mark_not_emoji_heading():
+    from praisonaiui.features.replay import REPLAY_MARK_SVG
+
+    assert REPLAY_MARK_SVG.startswith('<svg xmlns="http://www.w3.org/2000/svg"')
+    for banned in ("<script", "foreignObject", "onload", "javascript:"):
+        assert banned not in REPLAY_MARK_SVG
+    server_src = (ROOT / "src" / "praisonaiui" / "server.py").read_text(encoding="utf-8")
+    assert '"icon_svg": REPLAY_MARK_SVG' in server_src
+    dash = (FRONTEND / "dashboard.js").read_text(encoding="utf-8")
+    assert "function safeSvgIcon" in dash and "parsererror, script, foreignObject" in dash
+    assert "setPageIcon(iconSpan, page" in dash
+
+
+def test_dashboard_mobile_shell_gives_content_the_width():
+    dash = (FRONTEND / "dashboard.js").read_text(encoding="utf-8")
+    assert ".db-sidebar { position: fixed !important;" in dash
+    assert "#db-shell-header-slot { flex: 0 0 100%;" in dash
+    assert ".db-main { padding: 64px 16px 16px; }" in dash
+
+
+def test_theme_defaults_to_system():
+    view = VIEW.read_text(encoding="utf-8")
+    assert "@media (prefers-color-scheme:dark){.rp-root[data-theme=\"system\"]" in view
+    assert "'Theme: system'" in view

tests/unit/test_tracing_jsonl.py

@@ -0,0 +1,153 @@
+"""Tracing feature reads recorded runs from the context-trace JSONL directory.
+
+The old SDKTracingManager looked up ``praisonaiagents.trace.list_traces`` /
+``list_spans`` / ``get_trace``, which do not exist, so recorded runs never
+showed up and it silently fell back to an empty in-memory store.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pytest
+from starlette.applications import Starlette
+from starlette.testclient import TestClient
+
+FIXTURES = Path(__file__).resolve().parents[1] / "fixtures" / "replay"
+
+
+@pytest.fixture()
+def traces(tmp_path, monkeypatch):
+    d = tmp_path / "traces"
+    d.mkdir()
+    for name in ("team_handoff", "flow_parallel_loop", "legacy_v10"):
+        shutil.copy(FIXTURES / f"{name}.jsonl", d / f"{name}.jsonl")
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(d))
+    from praisonaiui.features import tracing
+
+    monkeypatch.setattr(tracing, "_tracing_manager", None)
+    return d
+
+
+@pytest.fixture()
+def client(traces):
+    from praisonaiui.features.tracing import TracingFeature
+
+    return TestClient(Starlette(routes=TracingFeature().routes()))
+
+
+def test_recorded_runs_are_listed_as_traces(client):
+    data = client.get("/api/traces").json()
+    ids = {t["id"] for t in data["traces"]}
+    assert {"team_handoff", "flow_parallel_loop", "legacy_v10"} <= ids
+    team = next(t for t in data["traces"] if t["id"] == "team_handoff")
+    assert team["source"] == "jsonl"
+    assert team["name"] == "Solar sail brief"
+    assert team["status"] == "completed"
+    assert team["duration_ms"] == pytest.approx(12250, abs=1)
+    assert team["span_count"] > 0
+    assert team["metadata"]["session_id"] == "sess-team-01"
+
+
+def test_agent_filter(client):
+    data = client.get("/api/traces?agent_id=Checker").json()
+    assert [t["id"] for t in data["traces"]] == ["legacy_v10"]
+
+
+def test_spans_from_start_end_pairs_via_parent_seq(client):
+    spans = client.get("/api/traces/spans?trace_id=team_handoff&limit=500").json()["spans"]
+    kinds = {}
+    for s in spans:
+        kinds[s["kind"]] = kinds.get(s["kind"], 0) + 1
+    assert kinds == {"session": 1, "workflow": 1, "llm": 5, "agent": 2, "task": 2, "tool": 4, "approval": 1}
+    by_id = {s["id"]: s for s in spans}
+    # tool span nests under the agent span that was open (parent_seq on the start)
+    tool = next(s for s in spans if s["kind"] == "tool" and s["name"] == "write_file")
+    parent = by_id[tool["parent_span_id"]]
+    assert parent["kind"] == "agent" and parent["agent_id"] == "Writer"
+    assert tool["status"] == "ok"
+    assert tool["duration_ms"] == pytest.approx(50.0)
+    assert tool["attributes"]["input"] == {"path": "docs/draft.md", "content": "[REDACTED]"}
+    # approval pairs requested -> decided by parent_seq even though the decision has no agent
+    appr = next(s for s in spans if s["kind"] == "approval")
+    assert appr["status"] == "ok"
+    assert appr["end_time"] == pytest.approx(1767225611.2)
+    # every span closed
+    assert all(s["status"] != "open" for s in spans)
+    assert all(s["trace_id"] == "team_handoff" for s in spans)
+
+
+def test_spans_for_legacy_file_fall_back_to_sequence_order(client):
+    spans = client.get("/api/traces/spans?trace_id=legacy_v10").json()["spans"]
+    by_id = {s["id"]: s for s in spans}
+    names = [(s["kind"], s["agent_id"]) for s in spans]
+    assert names == [
+        ("session", ""),
+        ("agent", "Assistant"),
+        ("llm", "Assistant"),
+        ("tool", "Assistant"),
+        ("llm", "Assistant"),
+        ("agent", "Checker"),
+        ("llm", "Checker"),
+    ]
+    calc = next(s for s in spans if s["kind"] == "tool")
+    assert by_id[calc["parent_span_id"]]["kind"] == "agent"
+    assert by_id[calc["parent_span_id"]]["agent_id"] == "Assistant"
+    checker_llm = spans[-1]
+    assert by_id[checker_llm["parent_span_id"]]["agent_id"] == "Checker"
+    assert all(s["status"] == "ok" for s in spans)
+
+
+def test_parallel_branch_spans_pair_within_branch(client):
+    spans = client.get("/api/traces/spans?trace_id=flow_parallel_loop&limit=500").json()["spans"]
+    tools = {s["name"]: s for s in spans if s["kind"] == "tool"}
+    assert tools["fetch_rss"]["duration_ms"] == pytest.approx(1250.0)
+    assert tools["search_papers"]["duration_ms"] == pytest.approx(1840.0)
+    assert tools["search_papers"]["attributes"]["branch_id"] == "gather/1"
+    assert tools["search_papers"]["attributes"]["cost_usd"] == pytest.approx(0.001)
+
+
+def test_get_trace_and_unknown(client):
+    r = client.get("/api/traces/legacy_v10")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["trace"]["id"] == "legacy_v10"
+    assert len(body["spans"]) == 7
+    assert client.get("/api/traces/does-not-exist").status_code == 404
+    assert client.get("/api/traces/../../etc/passwd").status_code == 404
+
+
+def test_health_reports_source(client, tmp_path, monkeypatch):
+    status = client.get("/api/traces/status").json()
+    assert status["source"] == "jsonl"
+    assert status["jsonl_traces"] == 3
+    from praisonaiui.features import tracing
+
+    monkeypatch.setenv("PRAISONAI_TRACES_DIR", str(tmp_path / "empty"))
+    monkeypatch.setattr(tracing, "_tracing_manager", None)
+    assert client.get("/api/traces/status").json()["source"] == "memory"
+
+
+def test_recorded_in_memory_traces_still_work(client):
+    r = client.post("/api/traces/record", json={"type": "trace", "id": "mem-1", "name": "manual"})
+    assert r.status_code == 200
+    ids = [t["id"] for t in client.get("/api/traces?limit=100").json()["traces"]]
+    assert "mem-1" in ids and "team_handoff" in ids
+    assert client.get("/api/traces/mem-1").json()["trace"]["name"] == "manual"
+
+
+def test_no_dead_sdk_lookups_remain():
+    src = (Path(__file__).resolve().parents[2] / "src" / "praisonaiui" / "features" / "tracing.py").read_text(encoding="utf-8")
+    for dead in ('"list_traces", None', '"list_spans", None', '"get_trace", None', "trace_module"):
+        assert dead not in src
+    from praisonaiui.features.tracing import JsonlTracingManager, SDKTracingManager
+
+    assert SDKTracingManager is JsonlTracingManager  # deprecated alias kept for imports
+
+
+def test_cli_status_mentions_source(traces):
+    from praisonaiui.features.tracing import TracingFeature
+
+    out = TracingFeature()._cli_status()
+    assert "Source: jsonl" in out

uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.14' and sys_platform == 'win32'",
@@ -207,7 +207,7 @@ wheels = [
 
 [[package]]
 name = "aiui"
-version = "0.3.146"
+version = "0.3.151"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },
@@ -1241,7 +1241,8 @@ dependencies = [
     { name = "mmh3" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.24.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "opentelemetry-api" },
     { name = "opentelemetry-exporter-otlp-proto-grpc" },
     { name = "opentelemetry-sdk" },
@@ -1311,6 +1312,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
 ]
 
+[[package]]
+name = "coloredlogs"
+version = "15.0.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "humanfriendly" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cc/c7/eed8f27100517e8c0e6b923d5f0845d0cb99763da6fdee00478f91db7325/coloredlogs-15.0.1.tar.gz", hash = "sha256:7c991aa71a4577af2f82600d8f8f3a89f936baeaf9b50a9c197da014e5bf16b0", size = 278520, upload-time = "2021-06-11T10:22:45.202Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a7/06/3d6badcf13db419e25b07041d9c7b4a2c331d3f4e7134445ec5df57714cd/coloredlogs-15.0.1-py2.py3-none-any.whl", hash = "sha256:612ee75c546f53e92e70049c9dbfcc18c935a2b9a53b66085ce9ef6a6e5c0934", size = 46018, upload-time = "2021-06-11T10:22:42.561Z" },
+]
+
 [[package]]
 name = "coverage"
 version = "7.13.2"
@@ -2450,6 +2463,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/92/e3/e3a44f54c8e2f28983fcf07f13d4260b37bd6a0d3a081041bc60b91d230e/huggingface_hub-1.6.0-py3-none-any.whl", hash = "sha256:ef40e2d5cb85e48b2c067020fa5142168342d5108a1b267478ed384ecbf18961", size = 612874, upload-time = "2026-03-06T14:19:16.844Z" },
 ]
 
+[[package]]
+name = "humanfriendly"
+version = "10.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyreadline3", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cc/3f/2c29224acb2e2df4d2046e4c73ee2662023c58ff5b113c4c1adac0886c43/humanfriendly-10.0.tar.gz", hash = "sha256:6b0b831ce8f15f7300721aa49829fc4e83921a9a301cc7f606be6686a2288ddc", size = 360702, upload-time = "2021-09-17T21:40:43.31Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f0/0f/310fb31e39e2d734ccaa2c0fb981ee41f7bd5056ce9bc29b2248bd569169/humanfriendly-10.0-py2.py3-none-any.whl", hash = "sha256:1697e1a8a8f550fd43c2865cd84542fc175a61dcb779b6fee18cf6b6ccba1477", size = 86794, upload-time = "2021-09-17T21:40:39.897Z" },
+]
+
 [[package]]
 name = "humanize"
 version = "4.15.0"
@@ -3355,7 +3380,8 @@ dependencies = [
     { name = "click" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.24.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "python-dotenv" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/fe/b6/8fdd991142ad3e037179a494b153f463024e5a211ef3ad948b955c26b4de/magika-0.6.2.tar.gz", hash = "sha256:37eb6ae8020f6e68f231bc06052c0a0cbe8e6fa27492db345e8dc867dbceb067", size = 3036634, upload-time = "2025-05-02T14:54:18.88Z" }
@@ -3379,7 +3405,8 @@ dependencies = [
     { name = "click" },
     { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime" },
+    { name = "onnxruntime", version = "1.23.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "onnxruntime", version = "1.24.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
     { name = "python-dotenv" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/a3/f3/3d1dcdd7b9c41d589f5cff252d32ed91cdf86ba84391cfc81d9d8773571d/magika-0.6.3.tar.gz", hash = "sha256:7cc52aa7359af861957043e2bf7265ed4741067251c104532765cd668c0c0cb1", size = 3042784, upload-time = "2025-10-30T15:22:34.499Z" }
@@ -4292,14 +4319,64 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/17/d3/b64c356a907242d719fc668b71befd73324e47ab46c8ebbbede252c154b2/olefile-0.47-py2.py3-none-any.whl", hash = "sha256:543c7da2a7adadf21214938bb79c83ea12b473a4b6ee4ad4bf854e7715e13d1f", size = 114565, upload-time = "2023-12-01T16:22:51.518Z" },
 ]
 
+[[package]]
+name = "onnxruntime"
+version = "1.23.2"
+source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version < '3.11' and sys_platform == 'win32'",
+    "python_full_version < '3.11' and sys_platform != 'win32'",
+]
+dependencies = [
+    { name = "coloredlogs" },
+    { name = "flatbuffers" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" } },
+    { name = "packaging" },
+    { name = "protobuf" },
+    { name = "sympy" },
+]
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/35/d6/311b1afea060015b56c742f3531168c1644650767f27ef40062569960587/onnxruntime-1.23.2-cp310-cp310-macosx_13_0_arm64.whl", hash = "sha256:a7730122afe186a784660f6ec5807138bf9d792fa1df76556b27307ea9ebcbe3", size = 17195934, upload-time = "2025-10-27T23:06:14.143Z" },
+    { url = "https://files.pythonhosted.org/packages/db/db/81bf3d7cecfbfed9092b6b4052e857a769d62ed90561b410014e0aae18db/onnxruntime-1.23.2-cp310-cp310-macosx_13_0_x86_64.whl", hash = "sha256:b28740f4ecef1738ea8f807461dd541b8287d5650b5be33bca7b474e3cbd1f36", size = 19153079, upload-time = "2025-10-27T23:05:57.686Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/4d/a382452b17cf70a2313153c520ea4c96ab670c996cb3a95cc5d5ac7bfdac/onnxruntime-1.23.2-cp310-cp310-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8f7d1fe034090a1e371b7f3ca9d3ccae2fabae8c1d8844fb7371d1ea38e8e8d2", size = 15219883, upload-time = "2025-10-22T03:46:21.66Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/56/179bf90679984c85b417664c26aae4f427cba7514bd2d65c43b181b7b08b/onnxruntime-1.23.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4ca88747e708e5c67337b0f65eed4b7d0dd70d22ac332038c9fc4635760018f7", size = 17370357, upload-time = "2025-10-22T03:46:57.968Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/6d/738e50c47c2fd285b1e6c8083f15dac1a5f6199213378a5f14092497296d/onnxruntime-1.23.2-cp310-cp310-win_amd64.whl", hash = "sha256:0be6a37a45e6719db5120e9986fcd30ea205ac8103fd1fb74b6c33348327a0cc", size = 13467651, upload-time = "2025-10-27T23:06:11.904Z" },
+    { url = "https://files.pythonhosted.org/packages/44/be/467b00f09061572f022ffd17e49e49e5a7a789056bad95b54dfd3bee73ff/onnxruntime-1.23.2-cp311-cp311-macosx_13_0_arm64.whl", hash = "sha256:6f91d2c9b0965e86827a5ba01531d5b669770b01775b23199565d6c1f136616c", size = 17196113, upload-time = "2025-10-22T03:47:33.526Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/a8/3c23a8f75f93122d2b3410bfb74d06d0f8da4ac663185f91866b03f7da1b/onnxruntime-1.23.2-cp311-cp311-macosx_13_0_x86_64.whl", hash = "sha256:87d8b6eaf0fbeb6835a60a4265fde7a3b60157cf1b2764773ac47237b4d48612", size = 19153857, upload-time = "2025-10-22T03:46:37.578Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/d8/506eed9af03d86f8db4880a4c47cd0dffee973ef7e4f4cff9f1d4bcf7d22/onnxruntime-1.23.2-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:bbfd2fca76c855317568c1b36a885ddea2272c13cb0e395002c402f2360429a6", size = 15220095, upload-time = "2025-10-22T03:46:24.769Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/80/113381ba832d5e777accedc6cb41d10f9eca82321ae31ebb6bcede530cea/onnxruntime-1.23.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:da44b99206e77734c5819aa2142c69e64f3b46edc3bd314f6a45a932defc0b3e", size = 17372080, upload-time = "2025-10-22T03:47:00.265Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/db/1b4a62e23183a0c3fe441782462c0ede9a2a65c6bbffb9582fab7c7a0d38/onnxruntime-1.23.2-cp311-cp311-win_amd64.whl", hash = "sha256:902c756d8b633ce0dedd889b7c08459433fbcf35e9c38d1c03ddc020f0648c6e", size = 13468349, upload-time = "2025-10-22T03:47:25.783Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/9e/f748cd64161213adeef83d0cb16cb8ace1e62fa501033acdd9f9341fff57/onnxruntime-1.23.2-cp312-cp312-macosx_13_0_arm64.whl", hash = "sha256:b8f029a6b98d3cf5be564d52802bb50a8489ab73409fa9db0bf583eabb7c2321", size = 17195929, upload-time = "2025-10-22T03:47:36.24Z" },
+    { url = "https://files.pythonhosted.org/packages/91/9d/a81aafd899b900101988ead7fb14974c8a58695338ab6a0f3d6b0100f30b/onnxruntime-1.23.2-cp312-cp312-macosx_13_0_x86_64.whl", hash = "sha256:218295a8acae83905f6f1aed8cacb8e3eb3bd7513a13fe4ba3b2664a19fc4a6b", size = 19157705, upload-time = "2025-10-22T03:46:40.415Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/35/4e40f2fba272a6698d62be2cd21ddc3675edfc1a4b9ddefcc4648f115315/onnxruntime-1.23.2-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:76ff670550dc23e58ea9bc53b5149b99a44e63b34b524f7b8547469aaa0dcb8c", size = 15226915, upload-time = "2025-10-22T03:46:27.773Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/88/9cc25d2bafe6bc0d4d3c1db3ade98196d5b355c0b273e6a5dc09c5d5d0d5/onnxruntime-1.23.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f9b4ae77f8e3c9bee50c27bc1beede83f786fe1d52e99ac85aa8d65a01e9b77", size = 17382649, upload-time = "2025-10-22T03:47:02.782Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/b4/569d298f9fc4d286c11c45e85d9ffa9e877af12ace98af8cab52396e8f46/onnxruntime-1.23.2-cp312-cp312-win_amd64.whl", hash = "sha256:25de5214923ce941a3523739d34a520aac30f21e631de53bba9174dc9c004435", size = 13470528, upload-time = "2025-10-22T03:47:28.106Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/41/fba0cabccecefe4a1b5fc8020c44febb334637f133acefc7ec492029dd2c/onnxruntime-1.23.2-cp313-cp313-macosx_13_0_arm64.whl", hash = "sha256:2ff531ad8496281b4297f32b83b01cdd719617e2351ffe0dba5684fb283afa1f", size = 17196337, upload-time = "2025-10-22T03:46:35.168Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/f9/2d49ca491c6a986acce9f1d1d5fc2099108958cc1710c28e89a032c9cfe9/onnxruntime-1.23.2-cp313-cp313-macosx_13_0_x86_64.whl", hash = "sha256:162f4ca894ec3de1a6fd53589e511e06ecdc3ff646849b62a9da7489dee9ce95", size = 19157691, upload-time = "2025-10-22T03:46:43.518Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/a1/428ee29c6eaf09a6f6be56f836213f104618fb35ac6cc586ff0f477263eb/onnxruntime-1.23.2-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:45d127d6e1e9b99d1ebeae9bcd8f98617a812f53f46699eafeb976275744826b", size = 15226898, upload-time = "2025-10-22T03:46:30.039Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/2b/b57c8a2466a3126dbe0a792f56ad7290949b02f47b86216cd47d857e4b77/onnxruntime-1.23.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8bace4e0d46480fbeeb7bbe1ffe1f080e6663a42d1086ff95c1551f2d39e7872", size = 17382518, upload-time = "2025-10-22T03:47:05.407Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/93/aba75358133b3a941d736816dd392f687e7eab77215a6e429879080b76b6/onnxruntime-1.23.2-cp313-cp313-win_amd64.whl", hash = "sha256:1f9cc0a55349c584f083c1c076e611a7c35d5b867d5d6e6d6c823bf821978088", size = 13470276, upload-time = "2025-10-22T03:47:31.193Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/3d/6830fa61c69ca8e905f237001dbfc01689a4e4ab06147020a4518318881f/onnxruntime-1.23.2-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9d2385e774f46ac38f02b3a91a91e30263d41b2f1f4f26ae34805b2a9ddef466", size = 15229610, upload-time = "2025-10-22T03:46:32.239Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/ca/862b1e7a639460f0ca25fd5b6135fb42cf9deea86d398a92e44dfda2279d/onnxruntime-1.23.2-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e2b9233c4947907fd1818d0e581c049c41ccc39b2856cc942ff6d26317cee145", size = 17394184, upload-time = "2025-10-22T03:47:08.127Z" },
+]
+
 [[package]]
 name = "onnxruntime"
 version = "1.24.3"
 source = { registry = "https://pypi.org/simple" }
+resolution-markers = [
+    "python_full_version >= '3.14' and sys_platform == 'win32'",
+    "python_full_version >= '3.14' and sys_platform != 'win32'",
+    "python_full_version == '3.13.*' and sys_platform == 'win32'",
+    "python_full_version == '3.13.*' and sys_platform != 'win32'",
+    "python_full_version == '3.12.*' and sys_platform == 'win32'",
+    "python_full_version == '3.12.*' and sys_platform != 'win32'",
+    "python_full_version == '3.11.*' and sys_platform == 'win32'",
+    "python_full_version == '3.11.*' and sys_platform != 'win32'",
+]
 dependencies = [
     { name = "flatbuffers" },
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
+    { name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" } },
     { name = "packaging" },
     { name = "protobuf" },
     { name = "sympy" },
@@ -5779,6 +5856,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/bd/24/12818598c362d7f300f18e74db45963dbcb85150324092410c8b49405e42/pyproject_hooks-1.2.0-py3-none-any.whl", hash = "sha256:9e5c6bfa8dcc30091c74b0cf803c81fdd29d94f01992a7707bc97babb1141913", size = 10216, upload-time = "2024-09-29T09:24:11.978Z" },
 ]
 
+[[package]]
+name = "pyreadline3"
+version = "3.5.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b6/6d/f94028646d7bbe6d9d873c47ee7c246f2d29129d253f0d96cb6fcab70733/pyreadline3-3.5.6.tar.gz", hash = "sha256:61e53218b99656091ddb077df9e71f25850e72e030b6183b39c9b7e6e4f4a9bf", size = 100368, upload-time = "2026-05-14T17:55:04.471Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f7/5e/35c856e186b74678c24927847ad9895a51f1bc02a0c6126477a6c6040064/pyreadline3-3.5.6-py3-none-any.whl", hash = "sha256:8449b734232e42a5dcd74048e39b60db2839a4c38cf3ae2bf7707d58b5389c0d", size = 85243, upload-time = "2026-05-14T17:55:03.262Z" },
+]
+
 [[package]]
 name = "pytest"
 version = "9.0.2"