Merge pull request #115 from SoundBlaster/codex/feature/FU-P13-T17-broker-hosted-webui

FU-P13-T17: Enable broker-hosted Web UI with shared multi-client telemetry

Author: SoundBlaster

SPECS/ARCHIVE/FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry.md

@@ -0,0 +1,78 @@
+# PRD: FU-P13-T17 — Enable broker-hosted Web UI with shared multi-client telemetry
+
+## 1. Objective
+
+Deliver a single-host broker topology where one long-lived broker process can also host the Web UI dashboard and expose telemetry aggregated across all broker-connected agents. This closes the current behavior gap where broker paths are transport-only and do not start dashboard services.
+
+The implementation must support:
+- `--broker-daemon --web-ui [--web-ui-config|--web-ui-port]` in one process
+- `--broker-spawn --web-ui ...` propagating Web UI args to the spawned daemon host
+- broker-side telemetry recording for `initialize` and `tools/call` lifecycles so all broker clients appear in one metrics/audit stream
+
+## 2. Success Criteria and Acceptance Tests
+
+### Success Criteria
+- Broker daemon can start Web UI server when requested without entering direct-mode bridge loop.
+- Auto-spawn proxy can bootstrap a broker host with Web UI enabled from the same client config.
+- Shared dashboard reflects tool requests/responses from multiple broker clients.
+- Existing direct-mode and broker-only behavior remains backward compatible.
+
+### Acceptance Tests
+- Unit test: `main()` broker-daemon + `--web-ui` starts server thread and wires telemetry store into broker transport.
+- Unit test: `main()` broker-spawn + `--web-ui` passes spawn args to `BrokerProxy` and includes Web UI flags.
+- Unit test: `UnixSocketServer` records request/response telemetry and client identity on broker-routed traffic.
+- Regression: existing broker tests and Web UI tests remain green.
+
+## 3. Test-First Plan
+
+1. Add failing unit tests first for new broker-daemon Web UI branch behavior in `tests/unit/test_main.py`.
+2. Add failing tests for `BrokerProxy` spawn-arg propagation in `tests/unit/test_broker_proxy.py`.
+3. Add failing transport telemetry tests in `tests/unit/test_broker_transport.py`.
+4. Implement runtime changes after tests exist.
+5. Run required gates:
+   - `PYTHONPATH=src pytest`
+   - `ruff check src/`
+   - `mypy src/`
+   - `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing`
+
+## 4. Execution Plan (Hierarchical TODO)
+
+### Phase A — Broker+WebUI runtime orchestration
+- Inputs: `__main__.py` argument parsing and broker mode branches.
+- Outputs: broker-daemon mode can initialize Web UI components and start dashboard thread.
+- Verification: broker path exits through `asyncio.run(daemon.run_forever())` with Web UI active when requested.
+
+### Phase B — Broker telemetry integration
+- Inputs: `broker/transport.py` request/response routing logic.
+- Outputs: optional metrics/audit hooks recorded for `initialize` and `tools/call` traffic.
+- Verification: request latency/error stats emitted into shared store and audit stream.
+
+### Phase C — Auto-spawn configuration consistency
+- Inputs: `broker/proxy.py` spawn command construction.
+- Outputs: optional spawn args support so `--broker-spawn --web-ui` uses one shared config story.
+- Verification: spawned daemon command contains requested Web UI args.
+
+### Phase D — Validation/reporting
+- Inputs: updated code + tests.
+- Outputs: `SPECS/INPROGRESS/FU-P13-T17_Validation_Report.md` with PASS/FAIL and gate outputs.
+- Verification: acceptance criteria checklist fully resolved.
+
+## 5. Decision Points and Constraints
+
+- Keep Web UI hosting on broker daemon only; do not start dashboard in short-lived `--broker-connect` proxy processes.
+- Preserve current stdout protocol behavior: JSON-RPC only, no dashboard logs on stdout.
+- Keep feature additive and backward-compatible for existing configs.
+- Review subject name: `fu_p13_t17_broker_hosted_webui`.
+
+## 6. Notes (Files likely touched)
+
+- `src/mcpbridge_wrapper/__main__.py`
+- `src/mcpbridge_wrapper/broker/transport.py`
+- `src/mcpbridge_wrapper/broker/proxy.py`
+- `tests/unit/test_main.py`
+- `tests/unit/test_broker_proxy.py`
+- `tests/unit/test_broker_transport.py`
+
+---
+**Archived:** 2026-02-28
+**Verdict:** PASS

SPECS/ARCHIVE/FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/FU-P13-T17_Validation_Report.md

@@ -0,0 +1,41 @@
+# Validation Report: FU-P13-T17 — Enable broker-hosted Web UI with shared multi-client telemetry
+
+**Date:** 2026-02-28
+**Task ID:** FU-P13-T17
+**Verdict:** PASS
+
+## Scope Implemented
+
+- Updated `src/mcpbridge_wrapper/__main__.py` to support broker-hosted dashboard runtime:
+  - `--broker-daemon --web-ui` now starts broker transport and Web UI in one process.
+  - `--web-ui-only` is now rejected when combined with broker flags.
+  - Added shared helpers for Web UI runtime preparation and broker spawn arg construction.
+- Updated `src/mcpbridge_wrapper/broker/proxy.py`:
+  - Added configurable `spawn_args` support for `--broker-spawn` flows.
+  - Ensured daemon spawn command includes `--broker-daemon` plus propagated Web UI args.
+- Updated `src/mcpbridge_wrapper/broker/transport.py`:
+  - Added optional metrics/audit dependencies to broker transport.
+  - Added broker-side client identity capture (`initialize`) and tool telemetry tracking (`tools/call` request/response latency + error state).
+- Added/updated tests:
+  - `tests/unit/test_main.py`
+  - `tests/unit/test_broker_proxy.py`
+  - `tests/unit/test_broker_transport.py`
+
+## Quality Gates
+
+- `PYTHONPATH=src pytest` → PASS (`689 passed, 5 skipped, 2 warnings`)
+- `ruff check src/` → PASS
+- `mypy src/` → PASS
+- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` → PASS
+  - Total coverage: **91.81%** (required: >= 90%)
+
+## Acceptance Criteria Check
+
+- [x] `mcpbridge-wrapper --broker-daemon --web-ui --web-ui-config <path>` starts broker socket and dashboard without launching direct-mode bridge loop.
+- [x] `mcpbridge-wrapper --broker-spawn --web-ui --web-ui-config <path>` can auto-start a broker host with Web UI enabled.
+- [x] Tool calls from multiple broker-connected clients appear in one dashboard metrics/audit stream.
+- [x] Existing direct mode and broker-only behavior remain backward compatible.
+
+## Notes
+
+- In this environment, direct `pytest` (without `PYTHONPATH=src`) is not used for gating because imports resolve via `PYTHONPATH=src`.

SPECS/ARCHIVE/INDEX.md

@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-02-28 (FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host)
+**Last Updated:** 2026-02-28 (FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| FU-P13-T17 | [FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/](FU-P13-T17_Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry/) | 2026-02-28 | PASS |
 | FU-P13-T16 | [FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/](FU-P13-T16_Document_multi_agent_MCP_usage_and_single_Web_UI_host/) | 2026-02-28 | PASS |
 | FU-P11-T2-4 | [FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/](FU-P11-T2-4_Add_one-command_Web_UI_restart_workflow/) | 2026-02-28 | PASS |
 | FU-P11-T2-3 | [FU-P11-T2-3_Reorder_sessions_from_the_last_to_the_first/](FU-P11-T2-3_Reorder_sessions_from_the_last_to_the_first/) | 2026-02-28 | PASS |
@@ -163,6 +164,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_fu_p13_t17_broker_hosted_webui.md](_Historical/REVIEW_fu_p13_t17_broker_hosted_webui.md) | Review report for FU-P13-T17 |
 | [REVIEW_fu_p13_t16_multi_agent_mcp_docs.md](_Historical/REVIEW_fu_p13_t16_multi_agent_mcp_docs.md) | Review report for FU-P13-T16 |
 | [REVIEW_P1-T1_project_structure.md](_Historical/REVIEW_P1-T1_project_structure.md) | Review report for P1-T1 |
 | [REVIEW_P1-T2_pyproject.toml.md](_Historical/REVIEW_P1-T2_pyproject.toml.md) | Review report for P1-T2 |
@@ -275,6 +277,8 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-02-28 | FU-P13-T17 | Archived REVIEW_fu_p13_t17_broker_hosted_webui report |
+| 2026-02-28 | FU-P13-T17 | Archived Enable_broker-hosted_Web_UI_with_shared_multi-client_telemetry (PASS) |
 | 2026-02-28 | FU-P13-T16 | Archived REVIEW_fu_p13_t16_multi_agent_mcp_docs report |
 | 2026-02-28 | FU-P13-T16 | Archived Document_multi_agent_MCP_usage_and_single_Web_UI_host (PASS) |
 | 2026-02-28 | FU-P11-T2-3 | Archived REVIEW_fu_p11_t2_3_session_ordering report |

SPECS/ARCHIVE/_Historical/REVIEW_fu_p13_t17_broker_hosted_webui.md

@@ -0,0 +1,30 @@
+## REVIEW REPORT — FU-P13-T17 broker-hosted Web UI
+
+**Scope:** `origin/main..HEAD`
+**Files:** 11
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- Broker-daemon runtime now owns optional Web UI startup, while proxy mode remains stdio-only except for daemon spawn argument propagation. This keeps short-lived clients lightweight and centralizes dashboard ownership.
+- Broker transport telemetry hooks are additive and optional (`metrics`/`audit` injected), preserving backward compatibility for broker-only deployments.
+
+### Tests
+- `PYTHONPATH=src pytest` → PASS (`689 passed, 5 skipped`)
+- `ruff check src/` → PASS
+- `mypy src/` → PASS
+- `PYTHONPATH=src pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` → PASS
+  - Coverage: **91.81%** (>= 90%)
+
+### Next Steps
+- FOLLOW-UP is not required; no actionable findings were identified.

SPECS/INPROGRESS/next.md

@@ -2,10 +2,11 @@
 
 ## Recently Archived
 
+- **FU-P13-T17** — Enable broker-hosted Web UI with shared multi-client telemetry (2026-02-28, PASS)
 - **FU-P13-T16** — Document multi-agent MCP usage and single Web UI host (2026-02-28, PASS)
 - **FU-P11-T2-4** — Add one-command Web UI restart workflow (2026-02-28, PASS)
-- **FU-P11-T2-3** — Reorder sessions from the last to the first (2026-02-28, PASS)
 
 ## Suggested Next Tasks
 
-- None (all workplan tasks are complete)
+- **FU-P13-T18** — Document unified single-config setup for broker + Web UI multi-agent workflows
+- **FU-P13-T19** — Add integration coverage for broker-hosted Web UI observability

SPECS/Workplan.md

@@ -2607,6 +2607,55 @@ Phase 9 Follow-up Backlog
 
 ---
 
+#### ✅ FU-P13-T17: Enable broker-hosted Web UI with shared multi-client telemetry — Completed (2026-02-28, PASS)
+- **Status:** ✅ Completed (2026-02-28, PASS)
+- **Description:** Implement a broker-mode runtime path where `--broker-daemon --web-ui` starts both the persistent broker and dashboard in one host process, and broker-side request/response telemetry feeds one shared Web UI view for all connected agents.
+- **Priority:** P0
+- **Dependencies:** P13-T10, FU-P13-T8
+- **Parallelizable:** no
+- **Outputs/Artifacts:**
+  - Updated `src/mcpbridge_wrapper/__main__.py` to support broker-daemon + Web UI startup orchestration
+  - Updated `src/mcpbridge_wrapper/broker/transport.py` to record tool telemetry for broker-routed clients
+  - Updated `src/mcpbridge_wrapper/broker/proxy.py` to propagate Web UI spawn args in `--broker-spawn` flows
+  - Updated unit tests in `tests/unit/test_main.py`, `tests/unit/test_broker_proxy.py`, and `tests/unit/test_broker_transport.py`
+- **Acceptance Criteria:**
+  - [x] `mcpbridge-wrapper --broker-daemon --web-ui --web-ui-config <path>` starts broker socket and dashboard without launching direct-mode bridge loop
+  - [x] `mcpbridge-wrapper --broker-spawn --web-ui --web-ui-config <path>` can auto-start a broker host with Web UI enabled
+  - [x] Tool calls from multiple broker-connected clients appear in one dashboard metrics/audit stream
+  - [x] Existing direct mode and broker-only behavior remain backward compatible
+
+---
+
+#### ⬜️ FU-P13-T18: Document unified single-config setup for broker + Web UI multi-agent workflows
+- **Description:** Update setup and troubleshooting docs so users can apply one MCP config across agents while reusing a shared broker host and one dashboard endpoint.
+- **Priority:** P1
+- **Dependencies:** FU-P13-T17
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - Updated `README.md`, `docs/broker-mode.md`, `docs/webui-setup.md`, and `docs/troubleshooting.md`
+  - Updated mapped DocC files in `Sources/XcodeMCPWrapper/Documentation.docc/`
+- **Acceptance Criteria:**
+  - [ ] Docs include one-config examples for Zed/Cursor/Claude/Codex with broker + dashboard expectations
+  - [ ] Docs clearly define dashboard ownership and fallback behavior
+  - [ ] Troubleshooting includes broker-hosted Web UI diagnostics
+
+---
+
+#### ⬜️ FU-P13-T19: Add integration coverage for broker-hosted Web UI observability
+- **Description:** Add automated test coverage that validates broker-mode telemetry visibility in Web UI APIs under multi-client request load.
+- **Priority:** P1
+- **Dependencies:** FU-P13-T17
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - New or updated integration tests under `tests/integration/webui/`
+  - Validation notes for deterministic multi-client telemetry assertions
+- **Acceptance Criteria:**
+  - [ ] Tests demonstrate aggregated metrics visibility for broker-connected clients
+  - [ ] Tests cover at least one error-path request and verify error reporting in metrics/audit output
+  - [ ] CI remains stable without flaky timing assumptions
+
+---
+
 ### Phase 14: Release 0.4.0 Readiness
 
 #### ✅ P14-T5: Stabilize broker Unix-socket permission test against path-length limits — Completed (2026-02-20, PASS)