agent-lab/docs/plans/2026-07-14-professional-debug-console-ui-design.md

Professional Debug Console UI Design

Status: approved for implementation

Date: 2026-07-14

Goal

Refactor the existing static Agent Lab page into a clearer professional debugging console while preserving its current FastAPI, WebSocket, session, tool, prompt, audit, and usage contracts.

The same change fixes EventPrompt state drift:

• in dual_agent mode, EventPrompt is visible, read-only, unique, and derived from the currently selected tools;
• in chat_agent_tools mode, EventPrompt is hidden and excluded from outbound system_prompts;
• mode changes, tool changes, session restores, and workspace snapshot restores all produce the same deterministic UI state.

The work is limited to the existing static frontend and focused regression tests. It does not introduce a frontend framework, bundler, backend protocol revision, or new runtime capability.

Chosen Approach

Keep the current server-rendered static entrypoint and refactor index.html, styles.css, and app.js in place.

This is preferred over introducing React/Vue because the page is an experimental service console rather than a product frontend. A framework migration would add build tooling, dependency cost, and regression surface without improving the core experiment. A CSS-only reskin is also insufficient because the requested behavior needs layout state, drawer state, collapsible controls, and one authoritative EventPrompt synchronization path.

Information Architecture

Top status bar

The top bar contains:

• Agent Lab identity;
• current session identity;
• connection state;
• current invocation-mode badge;
• the control that opens or closes the Audit/Usage drawer.

Connection and mode information remain visible without consuming the chat workspace.

Left control rail

The left rail groups controls into collapsible sections:

• Session — expanded by default;
• Tools — expanded by default;
• Agent Config — collapsed by default;
• Snapshot — collapsed by default.

Collapse state is persisted in browser storage. Existing control IDs and request behavior are preserved where practical so the change remains presentation-focused.

Tools are rendered as compact selectable rows/cards with a selected count and clear All/None actions. Tool selection remains available in both invocation modes because the selected set controls either the EventAgent catalog or ChatAgent provider tools.

Main chat workspace

The center column is the primary workspace:

• conversation history receives most available width and height;
• user, assistant, tool/status, warning, and error messages have distinct but restrained visual treatments;
• streaming and turn state remain visible without adding decorative animation;
• the composer stays anchored at the bottom of the workspace.

Round metrics are placed directly above the composer as a compact strip. They remain secondary to the conversation and do not move into the debug drawer.

Audit and usage drawer

Audit Replay and usage summaries move from an always-visible fixed column into a collapsible right drawer.

• Opening the drawer shows audit events and usage information together.
• Closing it returns the width to the chat workspace.
• Existing audit detail interactions are preserved.
• Drawer state is persisted in browser storage.

On narrow screens, the page becomes a stacked layout. Controls, chat, metrics/composer, and the opened debug drawer must remain usable without horizontal page scrolling.

Visual System

Use a light professional console palette with neutral surfaces, subtle borders, restrained shadows, and a small accent color for active states. The design should feel operational rather than decorative.

Define shared CSS variables for color, spacing, radii, control height, and typography. Buttons have explicit primary, secondary, and danger treatments. Status badges communicate connection, invocation mode, and active selections. Keyboard focus remains visible and color is not the only indicator of state.

The UI keeps the existing browser-native implementation and does not add icon libraries or external assets.

EventPrompt State Model

Single source of truth

EventPrompt is generated state, not a normal user-authored prompt item. One frontend refresh function owns all derived tool/mode presentation and performs these steps in a fixed order:

1. read the current invocation mode and selected tools;
2. update the selected-tool count and mode help/status;
3. remove every existing generated or legacy EventPrompt entry from the prompt list;
4. if the mode is dual_agent, generate and insert exactly one read-only EventPrompt from the selected tools;
5. if the mode is chat_agent_tools, leave EventPrompt absent and mark EventAgent-only model controls unavailable;
6. refresh any dependent visibility and disabled states.

Every relevant mutation calls this same function:

• individual tool checkbox change;
• All/None actions;
• invocation-mode change;
• initial application bootstrap;
• session restoration;
• workspace snapshot restoration;
• prompt-workspace restoration.

This replaces the current scattered update calls that can update mode help without updating EventPrompt.

Restore compatibility and deduplication

Persisted system_prompts are currently flat text values and do not preserve whether a value was generated EventPrompt content. Legacy restores can therefore treat an old EventPrompt as a custom prompt and append a newly generated EventPrompt, producing duplicates.

During restore, prompt entries matching the generated EventPrompt marker/shape are discarded before normal custom prompts are rebuilt. The derived-state refresh then inserts at most one current EventPrompt when required. User-authored prompts keep their order and content.

No storage schema migration is required for this UI repair. New saves continue to serialize only prompts that are valid for the current invocation mode.

Outbound request rules

collectSystemPrompts() must obey mode semantics rather than blindly serializing every visible prompt-list item:

• dual_agent: include user-authored prompts and the one current generated EventPrompt;
• chat_agent_tools: include user-authored prompts only, even if stale DOM or legacy persisted data contains EventPrompt-like content.

The request builder remains compatible with existing backend contracts. This filtering is a defensive boundary in addition to hiding/removing the generated item in the UI.

Configuration availability

In chat_agent_tools mode, EventAgent model configuration is visually unavailable because EventAgent does not perform the invocation decision. Shared runtime controls such as concurrency and timeout remain editable because direct tool execution still uses the shared event kernel and policies.

Switching back to dual_agent restores EventAgent model configuration availability and regenerates EventPrompt from the current tool selection.

Error and State Handling

• A failed session or snapshot restore retains the existing visible workspace and uses the existing feedback/error surface.
• Empty tool selection produces a deterministic EventPrompt representing no enabled events rather than retaining stale tool descriptions.
• UI state changes are synchronous and do not wait for a server round trip.
• Active-turn guards remain unchanged; the refactor must not weaken protection around session switching or configuration changes during a turn.
• The drawer and collapsible-section preferences are presentation state only and must not enter session runtime payloads.

File Boundaries

• src/agent_lab/presentation/static/index.html: semantic layout, collapsible groups, top status, drawer toggle, and accessible labels.
• src/agent_lab/presentation/static/styles.css: design tokens, responsive shell, control groups, tool rows, message roles, metrics/composer, and drawer styling.
• src/agent_lab/presentation/static/app.js: drawer/collapse persistence, unified derived-state refresh, restore deduplication, mode-aware prompt collection, and configuration availability.
• tests/: focused static/WebSocket contract regressions using the repository's existing test style.
• project docs: update UI/runtime guidance after behavior is verified.

Backend runtime, event-kernel, persistence, and WebSocket contracts are not changed unless a failing regression proves that a minimal compatibility adjustment is required. Any such adjustment becomes a separate follow-up todo rather than silently expanding Todo 53.

Verification

Focused regressions must prove:

• changing one tool immediately rebuilds EventPrompt with only selected tools;
• All/None actions synchronize the selected count and EventPrompt;
• loading a session or snapshot cannot create duplicate EventPrompt entries;
• chat_agent_tools hides EventPrompt and excludes it from system_prompts;
• switching back to dual_agent restores exactly one current EventPrompt;
• EventAgent-only model controls and shared execution controls have the correct mode-dependent availability;
• existing request/session/audit contracts remain intact.

Implementation verification will include:

• focused static and WebSocket tests;
• node --check src/agent_lab/presentation/static/app.js;
• uv run pytest;
• git diff --check;
• local browser QA at desktop and narrow widths, covering chat, tool selection, mode switching, prompt editing, session restore, drawer behavior, and composer usability.

Delivery Workflow

After this design is approved:

1. create the detailed Todo 53 implementation plan;
2. execute in an isolated git worktree;
3. use tests first for each behavior change;
4. delegate bounded implementation/review tasks to subagents while the main session owns planning and evaluation;
5. commit each completed todo with the solved problem and any relevant risk in the commit message;
6. record review-driven corrections as 53.x rows beneath Todo 53 instead of rewriting completed todo history;
7. update project documentation after final verification;
8. merge the verified result locally into the base branch.

Out of Scope

• React, Vue, another frontend framework, or a build pipeline;
• backend API/schema redesign;
• changing the two invocation-mode semantics;
• adding new event plugins or benchmark cases;
• a dark theme, theme switcher, or visual-companion assets;
• a general prompt persistence schema migration.