Mark/mesh-seed
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Decompose: CONV-003: Web Chat Interface #133

New issue
Closed
opened 2026-04-11 03:12:32 +00:00 by Mark · 2 comments
Mark commented 2026-04-11 03:12:32 +00:00
Owner
Copy link

Overview

Browser-based chat UI for interacting with the mesh. Builds on the existing CONV-001 (thread infrastructure, #131, closed) and CONV-002 (multi-turn context, #132, closed) to provide a web-based conversational interface.

Current State

  • CONV-001: Thread management API exists (POST/GET/DELETE threads, thread history endpoint)
  • CONV-002: Context retrieval and injection in workers works
  • CLI tools exist for mesh interaction (cli/mesh_cli.py, cli/client.py)
  • Flask HTTP entrypoint exists at runtime/http_entrypoint.py with REST API
  • flask-socketio is already a project dependency (in pyproject.toml)
  • FILE-001 (#135, open): File upload system — separate scope, not included here
  • No UI exists yet — only CLI and REST API clients

Technology Options

  • React/Vue.js frontend
  • WebSocket for real-time
  • Or Server-Sent Events for simpler implementation

Non-goals

  • File upload / drag-and-drop (covered by FILE-001 #135)
  • Voice/video chat
  • Native mobile app (responsive web only)

P1: WebSocket Backend + Static File Serving

Goal: Extend the Flask HTTP entrypoint with WebSocket support (Flask-SocketIO) for real-time bidirectional messaging, and serve static frontend files.

Approach candidates:

  • Add Flask-SocketIO to runtime/http_entrypoint.py — already a dependency, natural fit with existing Flask app
  • Add EventSource (SSE) endpoint as lighter alternative — simpler but unidirectional, less suitable for interactive chat
  • Standalone WebSocket server as a separate process — cleaner isolation but more operational overhead

Outputs:

  • runtime/ws_handler.py — WebSocket/SocketIO event handlers for chat messaging
  • runtime/static/ — directory for frontend static files, served by Flask
  • cli/web.py or cli/commands/web.py — optional CLI entrypoint to start web server
  • Tests in tests/unit/test_ws_handler.py

Acceptance criteria:

  • WebSocket connection established from browser to mesh backend
  • Messages sent from browser are received by the backend and routed as mesh intents
  • Response intents are streamed back to the browser in real-time
  • Existing REST API endpoints remain unaffected
  • Static frontend files served correctly via Flask
  • SocketIO event handlers tested: connect, disconnect, message, error
  • Graceful reconnection handling on disconnect

Files touched: runtime/http_entrypoint.py (amend — add SocketIO), runtime/ws_handler.py (create), runtime/__init__.py (amend), runtime/static/ (create), tests/unit/test_ws_handler.py (create), pyproject.toml (verify flask-socketio is listed)

P2: Chat Window UI + Message Display + Input

Goal: Build the core web chat interface — a single-page HTML/JS/CSS app with a chat window displaying user/assistant/system messages and a text input area, connected to the WebSocket backend.

Approach candidates:

  • Pure HTML+CSS+JS (vanilla) — no build step, simplest deployment, served directly by Flask
  • React (via CDN or bundled) — component model suits chat UI, but adds build complexity
  • Vue.js (via CDN) — lighter than React, good for single-page apps

Outputs:

  • runtime/static/index.html — main chat page shell
  • runtime/static/css/chat.css — chat UI styles
  • runtime/static/js/chat.js — chat client: WebSocket connection, message rendering, input handling
  • runtime/static/js/mesh_api.js — REST API client for thread management (CONV-001 endpoints)
  • Tests in tests/integration/test_chat_ui.py

Acceptance criteria:

  • Chat window renders messages in distinct user/assistant/system bubbles
  • User can type and send text messages via input box + send button
  • Messages are sent via WebSocket, responses appear in real-time
  • Enter key sends message, Shift+Enter inserts newline
  • Scroll position follows the conversation (auto-scroll to latest)
  • Page loads without errors in Chrome, Firefox, Safari
  • Chat UI works alongside existing REST API endpoints

Files touched: runtime/static/index.html (create), runtime/static/css/chat.css (create), runtime/static/js/chat.js (create), runtime/static/js/mesh_api.js (create), tests/integration/test_chat_ui.py (create)

P3: Thread Sidebar + Multi-Conversation Support

Goal: Add a thread sidebar listing all conversations, allowing the user to create, select, and switch between multiple concurrent chat conversations. Leverages the CONV-001 thread API.

Approach candidates:

  • Sidebar as a left-panel HTML element with thread list, toggle-able on mobile
  • Thread management via existing CONV-001 REST API (POST /threads, GET /threads, GET /threads/{id}/history)
  • Active thread state tracked in JS, loaded on thread switch
  • Thread titles auto-generated from first user message

Outputs:

  • runtime/static/css/sidebar.css — sidebar styles (responsive)
  • runtime/static/js/sidebar.js — sidebar component: thread list, create, switch, delete
  • Update runtime/static/index.html — integrate sidebar layout
  • Update runtime/static/js/chat.js — thread-aware message routing
  • runtime/static/js/thread_api.js — REST API client for thread CRUD
  • Tests in tests/integration/test_thread_sidebar.py

Acceptance criteria:

  • Sidebar lists all user conversations with title + last message preview
  • Clicking a thread in the sidebar loads its full conversation history
  • "New conversation" button creates a new thread and switches to it
  • Active thread is visually highlighted in sidebar
  • Messages are scoped to the active thread (sending in thread A stays in thread A)
  • Sidebar collapses on mobile (hamburger or swipe gesture)
  • Thread deletion with confirmation prompt
  • Thread title defaults to first user message (truncated to ~50 chars)

Files touched: runtime/static/index.html (amend), runtime/static/css/sidebar.css (create), runtime/static/js/sidebar.js (create), runtime/static/js/thread_api.js (create), runtime/static/js/chat.js (amend — thread context), tests/integration/test_thread_sidebar.py (create)

P4: Markdown Rendering + Typing Indicators + Intent Status

Goal: Enhance the chat UI with markdown message rendering, typing indicators when the mesh is processing, and visual display of intent lifecycle states (pending, working, completed, error).

Approach candidates:

  • Markdown rendering via client-side library (marked.js, showdown.js) — lightweight, no build step
  • Typing indicators: animated dots in the message area while awaiting response
  • Intent status: small badge/pill per message showing state transitions (pending→working→completed)
  • Keyboard shortcut for code blocks (triple backtick auto-close)

Outputs:

  • Update runtime/static/js/chat.js — markdown rendering, typing indicator component, status display
  • Update runtime/static/css/chat.css — markdown styles, typing animation, status badges
  • Include markdown library via CDN in runtime/static/index.html
  • Tests in tests/integration/test_chat_ui_enhancements.py

Acceptance criteria:

  • Messages render markdown: bold, italic, code, code blocks, lists, links, images
  • Code blocks have syntax highlighting (or at minimum monospace + background)
  • Typing indicator (animated dots) shows while mesh is processing a response
  • Intent status shows as a colored badge: yellow=pending, blue=working, green=completed, red=error
  • Status transitions animate smoothly (no flicker)
  • Markdown is sanitized (no XSS via <script> tags in message content)
  • Long code blocks are scrollable, not page-breaking
  • Typing indicator disappears promptly when response arrives

Files touched: runtime/static/index.html (amend — add markdown library CDN), runtime/static/js/chat.js (amend), runtime/static/css/chat.css (amend), tests/integration/test_chat_ui_enhancements.py (create)

P5: Auth/Session + Mobile Responsive + Error Handling

Goal: Add basic authentication/session management, ensure the UI works well on mobile devices, and polish error handling with retry capabilities.

Approach candidates:

  • Session tokens via existing Flask session infrastructure (server-side sessions)
  • Simple login page or API-key-based auth, with token stored in sessionStorage
  • Mobile-first CSS with flexbox/grid layout, media queries for breakpoints
  • Error toast/snackbar component for transient errors
  • Retry button on failed messages (re-send to active thread)

Outputs:

  • runtime/static/login.html — minimal login page (if auth is implemented)
  • runtime/static/js/auth.js — auth/session client: login, token refresh, session check
  • Update runtime/static/css/chat.css — responsive breakpoints, mobile layout
  • Update runtime/ws_handler.py — auth verification on WebSocket connect
  • Error handling component in runtime/static/js/chat.js
  • Tests in tests/integration/test_auth_session.py and tests/integration/test_mobile_responsive.py

Acceptance criteria:

  • User must authenticate before accessing the chat UI
  • Session persists across page reloads (within session lifetime)
  • Session expires after configurable idle timeout
  • UI renders correctly on mobile (viewport ≤ 480px): sidebar collapses, messages full-width, input bar at bottom
  • Touch interactions work (tap to send, swipe to show sidebar, scroll chat history)
  • Network errors show a non-disruptive toast notification
  • Failed message delivery shows retry button; clicking retry re-sends via WebSocket
  • Loading states shown during initial page load and reconnection
  • Rate limit errors display a friendly "slow down" message with retry-after countdown

Files touched: runtime/ws_handler.py (amend — auth on connect), runtime/static/login.html (create), runtime/static/js/auth.js (create), runtime/static/index.html (amend — auth check), runtime/static/js/chat.js (amend — error/retry), runtime/static/css/chat.css (amend — responsive), tests/integration/test_auth_session.py (create), tests/integration/test_mobile_responsive.py (create)

Related

  • CONV-001: Conversation Interface Infrastructure (#131, closed — provides thread API)
  • CONV-002: Multi-turn Context Management (#132, closed — provides context injection)
  • FILE-001: File Upload System (#135, open — separate scope)

Priority

MEDIUM - User-facing feature

## Overview Browser-based chat UI for interacting with the mesh. Builds on the existing CONV-001 (thread infrastructure, #131, closed) and CONV-002 (multi-turn context, #132, closed) to provide a web-based conversational interface. ## Current State - CONV-001: Thread management API exists (POST/GET/DELETE threads, thread history endpoint) - CONV-002: Context retrieval and injection in workers works - CLI tools exist for mesh interaction (`cli/mesh_cli.py`, `cli/client.py`) - Flask HTTP entrypoint exists at `runtime/http_entrypoint.py` with REST API - `flask-socketio` is already a project dependency (in pyproject.toml) - FILE-001 (#135, open): File upload system — **separate scope, not included here** - No UI exists yet — only CLI and REST API clients ## Technology Options - React/Vue.js frontend - WebSocket for real-time - Or Server-Sent Events for simpler implementation ## Non-goals - File upload / drag-and-drop (covered by FILE-001 #135) - Voice/video chat - Native mobile app (responsive web only) --- ### P1: WebSocket Backend + Static File Serving **Goal:** Extend the Flask HTTP entrypoint with WebSocket support (Flask-SocketIO) for real-time bidirectional messaging, and serve static frontend files. **Approach candidates:** - Add Flask-SocketIO to `runtime/http_entrypoint.py` — already a dependency, natural fit with existing Flask app - Add EventSource (SSE) endpoint as lighter alternative — simpler but unidirectional, less suitable for interactive chat - Standalone WebSocket server as a separate process — cleaner isolation but more operational overhead **Outputs:** - `runtime/ws_handler.py` — WebSocket/SocketIO event handlers for chat messaging - `runtime/static/` — directory for frontend static files, served by Flask - `cli/web.py` or `cli/commands/web.py` — optional CLI entrypoint to start web server - Tests in `tests/unit/test_ws_handler.py` **Acceptance criteria:** - [ ] WebSocket connection established from browser to mesh backend - [ ] Messages sent from browser are received by the backend and routed as mesh intents - [ ] Response intents are streamed back to the browser in real-time - [ ] Existing REST API endpoints remain unaffected - [ ] Static frontend files served correctly via Flask - [ ] SocketIO event handlers tested: connect, disconnect, message, error - [ ] Graceful reconnection handling on disconnect **Files touched:** `runtime/http_entrypoint.py` (amend — add SocketIO), `runtime/ws_handler.py` (create), `runtime/__init__.py` (amend), `runtime/static/` (create), `tests/unit/test_ws_handler.py` (create), `pyproject.toml` (verify flask-socketio is listed) --- ### P2: Chat Window UI + Message Display + Input **Goal:** Build the core web chat interface — a single-page HTML/JS/CSS app with a chat window displaying user/assistant/system messages and a text input area, connected to the WebSocket backend. **Approach candidates:** - Pure HTML+CSS+JS (vanilla) — no build step, simplest deployment, served directly by Flask - React (via CDN or bundled) — component model suits chat UI, but adds build complexity - Vue.js (via CDN) — lighter than React, good for single-page apps **Outputs:** - `runtime/static/index.html` — main chat page shell - `runtime/static/css/chat.css` — chat UI styles - `runtime/static/js/chat.js` — chat client: WebSocket connection, message rendering, input handling - `runtime/static/js/mesh_api.js` — REST API client for thread management (CONV-001 endpoints) - Tests in `tests/integration/test_chat_ui.py` **Acceptance criteria:** - [ ] Chat window renders messages in distinct user/assistant/system bubbles - [ ] User can type and send text messages via input box + send button - [ ] Messages are sent via WebSocket, responses appear in real-time - [ ] Enter key sends message, Shift+Enter inserts newline - [ ] Scroll position follows the conversation (auto-scroll to latest) - [ ] Page loads without errors in Chrome, Firefox, Safari - [ ] Chat UI works alongside existing REST API endpoints **Files touched:** `runtime/static/index.html` (create), `runtime/static/css/chat.css` (create), `runtime/static/js/chat.js` (create), `runtime/static/js/mesh_api.js` (create), `tests/integration/test_chat_ui.py` (create) --- ### P3: Thread Sidebar + Multi-Conversation Support **Goal:** Add a thread sidebar listing all conversations, allowing the user to create, select, and switch between multiple concurrent chat conversations. Leverages the CONV-001 thread API. **Approach candidates:** - Sidebar as a left-panel HTML element with thread list, toggle-able on mobile - Thread management via existing CONV-001 REST API (POST /threads, GET /threads, GET /threads/{id}/history) - Active thread state tracked in JS, loaded on thread switch - Thread titles auto-generated from first user message **Outputs:** - `runtime/static/css/sidebar.css` — sidebar styles (responsive) - `runtime/static/js/sidebar.js` — sidebar component: thread list, create, switch, delete - Update `runtime/static/index.html` — integrate sidebar layout - Update `runtime/static/js/chat.js` — thread-aware message routing - `runtime/static/js/thread_api.js` — REST API client for thread CRUD - Tests in `tests/integration/test_thread_sidebar.py` **Acceptance criteria:** - [ ] Sidebar lists all user conversations with title + last message preview - [ ] Clicking a thread in the sidebar loads its full conversation history - [ ] "New conversation" button creates a new thread and switches to it - [ ] Active thread is visually highlighted in sidebar - [ ] Messages are scoped to the active thread (sending in thread A stays in thread A) - [ ] Sidebar collapses on mobile (hamburger or swipe gesture) - [ ] Thread deletion with confirmation prompt - [ ] Thread title defaults to first user message (truncated to ~50 chars) **Files touched:** `runtime/static/index.html` (amend), `runtime/static/css/sidebar.css` (create), `runtime/static/js/sidebar.js` (create), `runtime/static/js/thread_api.js` (create), `runtime/static/js/chat.js` (amend — thread context), `tests/integration/test_thread_sidebar.py` (create) --- ### P4: Markdown Rendering + Typing Indicators + Intent Status **Goal:** Enhance the chat UI with markdown message rendering, typing indicators when the mesh is processing, and visual display of intent lifecycle states (pending, working, completed, error). **Approach candidates:** - Markdown rendering via client-side library (marked.js, showdown.js) — lightweight, no build step - Typing indicators: animated dots in the message area while awaiting response - Intent status: small badge/pill per message showing state transitions (pending→working→completed) - Keyboard shortcut for code blocks (triple backtick auto-close) **Outputs:** - Update `runtime/static/js/chat.js` — markdown rendering, typing indicator component, status display - Update `runtime/static/css/chat.css` — markdown styles, typing animation, status badges - Include markdown library via CDN in `runtime/static/index.html` - Tests in `tests/integration/test_chat_ui_enhancements.py` **Acceptance criteria:** - [ ] Messages render markdown: **bold**, *italic*, `code`, ```code blocks```, lists, links, images - [ ] Code blocks have syntax highlighting (or at minimum monospace + background) - [ ] Typing indicator (animated dots) shows while mesh is processing a response - [ ] Intent status shows as a colored badge: yellow=pending, blue=working, green=completed, red=error - [ ] Status transitions animate smoothly (no flicker) - [ ] Markdown is sanitized (no XSS via `<script>` tags in message content) - [ ] Long code blocks are scrollable, not page-breaking - [ ] Typing indicator disappears promptly when response arrives **Files touched:** `runtime/static/index.html` (amend — add markdown library CDN), `runtime/static/js/chat.js` (amend), `runtime/static/css/chat.css` (amend), `tests/integration/test_chat_ui_enhancements.py` (create) --- ### P5: Auth/Session + Mobile Responsive + Error Handling **Goal:** Add basic authentication/session management, ensure the UI works well on mobile devices, and polish error handling with retry capabilities. **Approach candidates:** - Session tokens via existing Flask session infrastructure (server-side sessions) - Simple login page or API-key-based auth, with token stored in sessionStorage - Mobile-first CSS with flexbox/grid layout, media queries for breakpoints - Error toast/snackbar component for transient errors - Retry button on failed messages (re-send to active thread) **Outputs:** - `runtime/static/login.html` — minimal login page (if auth is implemented) - `runtime/static/js/auth.js` — auth/session client: login, token refresh, session check - Update `runtime/static/css/chat.css` — responsive breakpoints, mobile layout - Update `runtime/ws_handler.py` — auth verification on WebSocket connect - Error handling component in `runtime/static/js/chat.js` - Tests in `tests/integration/test_auth_session.py` and `tests/integration/test_mobile_responsive.py` **Acceptance criteria:** - [ ] User must authenticate before accessing the chat UI - [ ] Session persists across page reloads (within session lifetime) - [ ] Session expires after configurable idle timeout - [ ] UI renders correctly on mobile (viewport ≤ 480px): sidebar collapses, messages full-width, input bar at bottom - [ ] Touch interactions work (tap to send, swipe to show sidebar, scroll chat history) - [ ] Network errors show a non-disruptive toast notification - [ ] Failed message delivery shows retry button; clicking retry re-sends via WebSocket - [ ] Loading states shown during initial page load and reconnection - [ ] Rate limit errors display a friendly "slow down" message with retry-after countdown **Files touched:** `runtime/ws_handler.py` (amend — auth on connect), `runtime/static/login.html` (create), `runtime/static/js/auth.js` (create), `runtime/static/index.html` (amend — auth check), `runtime/static/js/chat.js` (amend — error/retry), `runtime/static/css/chat.css` (amend — responsive), `tests/integration/test_auth_session.py` (create), `tests/integration/test_mobile_responsive.py` (create) --- ## Related - CONV-001: Conversation Interface Infrastructure (#131, closed — provides thread API) - CONV-002: Multi-turn Context Management (#132, closed — provides context injection) - FILE-001: File Upload System (#135, open — separate scope) ## Priority MEDIUM - User-facing feature
Mark commented 2026-06-20 20:47:01 +00:00
Author
Owner
Copy link

Auto-triage: needs decompose

Marked triage-approved + needs-decompose. decompose-executor will pick this up and break it into implementable sub-issues.

## Auto-triage: needs decompose Marked `triage-approved` + `needs-decompose`. decompose-executor will pick this up and break it into implementable sub-issues.
Mark changed title from CONV-003: Web Chat Interface to Decompose: CONV-003: Web Chat Interface 2026-07-15 11:38:32 +00:00
Mark commented 2026-07-15 11:38:53 +00:00
Author
Owner
Copy link

This issue has been decomposed into the following sub-issues:

# Title Phase Scope
#236 Decompose: CONV-003: Web Chat Interface — Phase 1: WebSocket Goal: Extend the Flask HTTP entrypoint with WebSocket support (Flask-SocketI
#237 Decompose: CONV-003: Web Chat Interface — Phase 2: Chat Wind Goal: Build the core web chat interface — a single-page HTML/JS/CSS app with
#238 Decompose: CONV-003: Web Chat Interface — Phase 3: Thread Si Goal: Add a thread sidebar listing all conversations, allowing the user to c
#239 Decompose: CONV-003: Web Chat Interface — Phase 4: Markdown Goal: Enhance the chat UI with markdown message rendering, typing indicators
#240 Decompose: CONV-003: Web Chat Interface — Phase 5: Auth/Sess Goal: Add basic authentication/session management, ensure the UI works well

Each sub-issue has been labeled with triage-approved and is ready for queue routing.

This issue has been decomposed into the following sub-issues: | # | Title | Phase Scope | |---|-------|-------------| | #236 | Decompose: CONV-003: Web Chat Interface — Phase 1: WebSocket | **Goal:** Extend the Flask HTTP entrypoint with WebSocket support (Flask-SocketI | | #237 | Decompose: CONV-003: Web Chat Interface — Phase 2: Chat Wind | **Goal:** Build the core web chat interface — a single-page HTML/JS/CSS app with | | #238 | Decompose: CONV-003: Web Chat Interface — Phase 3: Thread Si | **Goal:** Add a thread sidebar listing all conversations, allowing the user to c | | #239 | Decompose: CONV-003: Web Chat Interface — Phase 4: Markdown | **Goal:** Enhance the chat UI with markdown message rendering, typing indicators | | #240 | Decompose: CONV-003: Web Chat Interface — Phase 5: Auth/Sess | **Goal:** Add basic authentication/session management, ensure the UI works well | Each sub-issue has been labeled with `triage-approved` and is ready for queue routing.
Mark closed this issue 2026-07-15 11:38:53 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
mesh-seed#142-gate-verify-pass-07b1f89
Labels
Clear labels   
blocked:children

   
blocked:commit-ready-failed

   
blocked:depends-231

Depends on #231 (Discord Bot Foundation) landing first. Do not pick until #231 is closed.

  
blocked:depends-236

Depends on #236 (Phase 1) landing first. Do not pick until #236 is closed.

  
blocked:depends-237

Depends on #237 (Phase 2) landing first. Do not pick until #237 is closed.

  
blocked:depends-238

Depends on #238 (Phase 3) landing first. Do not pick until #238 is closed.

  
blocked:depends-239

Depends on #239 (Phase 4) landing first. Do not pick until #239 is closed.

  
blocked:gate-fetch

   
blocked:gate-fetch

   
blocked:gate-lint

   
blocked:gate-research

   
blocked:needs-attention

Janitor escalated: pipeline terminated without producing expected changes. Human review required.

  
blocked:needs-decision

   
blocked:no-changes

   
blocked:no-procedure

   
blocked:preflight

Preflight check failed

  
blocked:verify-failed

   
bug

Something is broken

  
enhancement

New feature or request

  
feature-request

   
high-priority

Critical path items

  
in-progress

Issue is currently being worked on by a quickfix runner

  
lint-cleanup

Repo lint baseline is dirty

  
needs-decompose

   
needs-triage

   
ops-retry

   
ops-task

Operations task — install, configure, deploy, API calls

  
phase-5

Phase 5 Self-Building Infrastructure

  
quickfix

Pipe to opencode for direct fix

  
security/medium

Medium severity security issue

  
self-building

Autonomous code generation and self-improvement

  
triage-approved

Approved by triage — queued for fixer pipeline

No labels
blocked:children
blocked:commit-ready-failed
blocked:depends-231
blocked:depends-236
blocked:depends-237
blocked:depends-238
blocked:depends-239
blocked:gate-fetch
blocked:gate-fetch
blocked:gate-lint
blocked:gate-research
blocked:needs-attention
blocked:needs-decision
blocked:no-changes
blocked:no-procedure
blocked:preflight
blocked:verify-failed
bug
enhancement
feature-request
high-priority
in-progress
lint-cleanup
needs-decompose
needs-triage
ops-retry
ops-task
phase-5
quickfix
security/medium
self-building
triage-approved
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Mark/mesh-seed#133
No description provided.