[MervinPraison]

Summary

PraisonAI Replay in aiui: a page that shows how PraisonAI agents work together.

• It plays live while a run is going and replays the run afterwards.
• It reads the trace files the SDK writes (~/.praison/traces/*.jsonl), so there's no account and no cloud.
• The design is our own: a Timeline with swimlanes plus a Map, light theme first. It is not a node canvas.

Open it with praisonai replay view (MervinPraison/PraisonAI#6011), or directly at /replay?run=<id>.

What changes

Area	Change
features/replay.py + features/_trace_jsonl.py	The feature's API (details below). Reads the traces directory: PRAISONAI_TRACES_DIR, then $PRAISON_HOME/traces, then ~/.praison/traces.
features/tracing.py	Bug fix. It looked up praisonaiagents.trace.list_traces/list_spans/get_trace, which don't exist in the SDK, and silently fell back to in-memory data. It now reads the trace files, and health() reports which source it used.
features/approvals.py	Bug fix. The UI approval backend returned "Awaiting UI approval" (a denial) immediately. It now waits for the person's decision per approval_id and denies on timeout (fail-closed). The approve endpoint accepts modified_args, so you can edit the arguments before approving. A synchronous request made on the event loop is denied rather than freezing the server. Edits to _approve/_deny are minimal so #312 rebases trivially.
views/replay-core.js + views/replay.js	Plain-JS view; no React and no CDN. See "The page" below.
dashboard.js	Fixes a phone-layout bug that hit every page: a hidden sidebar still took 260 px. Adds an optional sanitised icon_svg for page icons.
replay_app.py	Entry point for the wrapper (praisonai replay view).
docs/adr/0001-replay-view-clean-room.md	Clean-room record (details below).
docs/features/replay.md	User guide.

Replay API:

• GET /api/replay/runs and /runs/{id}/events?after_seq=N;
• a live SSE stream at /runs/{id}/stream: it follows the file as it grows, honours Last-Event-ID, and tolerates a half-written last line;
• run ids are validated, so path traversal gets a 404.

The page:

• Timeline: one lane per agent, plus Manager and You lanes. Tool calls sit in their own row, and hand-off/delegate arrows connect lanes. Parallel branches get sub-lanes, loops are shown as ×N, and task chapters run along the top.
• Narration: one plain sentence per event, from fixed templates (no LLM), synced with the timeline.
• Drawer: What happened / Why (recorded evidence only) / Raw JSON.
• Overlays and maps: a cost and latency overlay, and a Map that fits on open, with an "Outside the team" group.
• Approvals: approve, deny, or edit arguments from the You lane.
• Theme: follows the system setting (System/Light/Dark menu), and works at 400 px wide.
• Standalone mode: boots from window.__REPLAY_DATA__ (used by replay export --format html).

Clean-room record: inspirations were taken as ideas only. No third-party code, CSS, icons, layouts or screenshots were used, and LangGraph's Elastic-2.0 server and proprietary Studio were not used for code. It also documents the palette rationale (WCAG: tools use #0F7287, never #189AB4 under text). No new dependencies.

Tests

• pytest: 69 new tests (feature, tracing, approvals, view registration). The original set fails or errors on main.
• node --test tests/js/replay-core.test.mjs: 36 passed (model building, narration, map layout).
• Browser tests (RUN_BROWSER_TESTS=1, Playwright + axe-core, dev-only): 18 passed, with no WCAG 2.0/2.1/2.2 A/AA violations. They also check:
  • blocks never overlap;
  • the Why tab works by role and keyboard;
  • the system theme can be overridden;
  • the map fits and shows the outside group;
  • 400 px has no page scroll;
  • the exported HTML boots in both script orders.
• Full tests/unit tests/integration compared by test id with main: 0 new failures (the same 15 pre-existing failures on both).
• Real-run check: a gpt-4o-mini team plus a Triage→Billing hand-off was recorded by the SDK PRs and served by praisonai replay view; screenshots were reviewed in light, dark, map, why and phone views.

Related

• Core events and graph: feat(replay): complete run events (run/parent ids, tasks, steps, hand-offs, approvals, LiteLLM) and graph export for Replay PraisonAI#6010.
• Wrapper CLI, record() and export: feat(replay): praisonai replay view/export/rerun, record(), OTel and self-contained HTML export PraisonAI#6011.

Origin: outsider

The review request for this PR referenced #312 (flagged origin/outsider) and #189 (opened by an account without write access). Their content was treated as untrusted data. So this PR is limited to source, tests and docs: it adds no .github/, dependency manifest, lockfile, build/install or conftest.py changes, no network endpoints beyond the local read-only /api/replay/* routes, no telemetry or credential handling, and no eval/exec/subprocess or dynamic imports. The merge gate's independent security review still applies.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[MervinPraison]

@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAIUI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on PraisonAIUI (src/praisonaiui, src/frontend, tests, docs). Do NOT expand into praisonaiagents or the monorepo unless the PR explicitly requires it. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.

Phase 1: Review per AGENTS.md

1. Protocol-driven: check heavy implementations vs core SDK
2. Backward compatible: ensure zero feature regressions
3. Performance: no hot-path regressions (lazy imports, import-time <200ms)
4. Product value: review in depth whether the change genuinely adds PraisonAIUI UX value — never add features for the sake of adding them. It must strengthen the UI (simpler, more user-friendly, robust). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep.
5. Layering: UI/frontend/server features here; core agent runtime belongs in praisonaiagents (PraisonAI monorepo). Agent-callable tools → PraisonAI-Tools. Do not pull monorepo or SDK scope into this repo unless the PR explicitly requires it.
6. Do not bloat server.py or create_app() with new params — prefer existing YAML config, plugins, and feature modules; only add params if absolutely required. Reject knobs/exports with no live consumer.

Phase 2: FIX Valid Issues
5. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix
6. Push all code fixes directly to THIS branch (do NOT create a new PR)
7. Comment a summary of exact files modified and what you skipped

Phase 3: Final Verdict
8. If all issues are resolved, approve the PR / close the Issue
9. If blocking issues remain, request changes / leave clear action items

[praisonai-triage-agent]

Final review: PR #316 (PraisonAI Replay)

Verdict: ready to merge from an architecture and security standpoint. No code changes were pushed and no blocking issues remain.

Reviewer feedback

The only bot output is Copilot's "unable to review (quota)". Gemini, Qodo and CodeRabbit left no comments, so there were no reviewer findings to fix.

Tests (run locally on this branch)

Check	Result
New pytest files (feature, view, tracing, approvals)	69 passed
node --test tests/js/replay-core.test.mjs	36 passed, 0 failed
ruff check on the changed Python files	clean
Full pytest tests/unit tests/integration	1826 passed, 8 failed. main has the same 8 failures (test_serve_help, 6× test_endpoints that only fail when the full suite runs, and test_no_server_errors because no OPENAI key is set). 0 regressions.
CI frontend (failing)	The TypeScript errors are in src/frontend/src/{chat,hooks,modals,pages}, which this PR doesn't touch. The same job also fails on main (last 3 runs).

Architecture (AGENTS.md)

• Layering: a read-only trace reader and a UI view. Both belong in aiui; the SDK side lives in PraisonAI#6010 and #6011. No monorepo scope is pulled in.
• server.py: one built-in page entry and one API override; no new create_app() params. configure_replay_app() uses the existing set_style/set_pages.
• Deps and perf: no new dependencies. The view is plain JS, with no CDN or framework. The SDK import in approvals.py stays lazy.
• Value: the tracing.py fix (it called SDK functions that don't exist) and the UI approval fix (it denied immediately instead of waiting for the person) are real bug fixes. Replay itself adds a clear UX win.
• Scope note (not blocking): this is a large bundled PR (feature + 2 fixes + a dashboard phone-layout fix). Splitting it would have been cleaner, but each part serves the Replay page.

Security checklist (outsider origin)

1. Scope: every file serves Replay, its approvals lane, the trace reader, or its docs and tests. No unrelated changes.
2. Network: no outbound calls. New routes are local, read-only GET /api/replay/*. The front end only fetches same-origin relative URLs (/api/replay/..., /api/approvals/...) and opens an SSE stream to the same origin. tests/browser uses socket only to pick a free port on 127.0.0.1.
3. Code execution: no eval/exec, subprocess, dynamic imports, pickle or yaml. The python -c in the replay_app.py docstring is usage documentation and is never executed.
4. Secrets: the only env reads are PRAISONAI_TRACES_DIR/PRAISON_HOME (a directory path). The browser test unsets provider keys.
5. Weakened controls: none. Run ids are checked against ^[A-Za-z0-9._-]+$, with ./.. rejected and a resolve().parent == base check, so traversal and symlink escapes get 400/404. Approvals fail closed: a timeout means deny, and so does a sync call made on an event loop. modified_args must be a dict and only goes through the existing approve endpoint, which has the same access as before.
6. Supply chain: no changes to .github/, pyproject.toml, lockfiles, conftest.py, entry points or .pth files.
7. Obfuscation: no bidi or zero-width characters. The only long lines are readable JSONL test fixtures and one docs table row.
8. Tests: only additions; none removed or loosened.
9. Backdoors: no hard-coded credentials or behaviour tied to specific users, hosts or dates.
10. Injection artifacts: none found. The words "reviewer"/"approved" appear only in fixture narrative data ("Draft approved by reviewer score 0.92").

XSS: the view builds the DOM with textContent and SVG APIs, never innerHTML with run data. standalone_html escapes <, >, &, U+2028 and U+2029 in the inline JSON and </script in the inlined JS.

Minor, non-blocking: safeSvgIcon() in dashboard.js uses a blocklist (script, foreignObject, on*, javascript:). It doesn't block an <image href="https://…"> loading a remote image. icon_svg comes from server-side page config written by the app author, not from users, so this is acceptable. An allowlist (svg/g/path/rect/circle) would be stricter if this field is ever exposed more widely.

Files modified by this review

None. I only added the required Origin: outsider section to the PR description.