docs: plan real queue websocket loop

docs/plans/todo-13-real-queue-websocket-loop.md

@@ -0,0 +1,97 @@
+# Todo 13 Real Queue WebSocket Loop Plan
+
+**Status:** in_progress
+
+## Goal
+
+Make runtime queues real producer/consumer boundaries and let WebSocket run separate upstream and downstream tasks.
+
+## Why
+
+The original queue requirement names producers and consumers explicitly:
+
+- input queue: WebSocket upstream and EventAgent replies produce; ChatAgent consumes.
+- output queue: ChatAgent produces; WebSocket downstream consumes.
+- event queue: ChatAgent produces; EventAgent consumes.
+
+The current runtime logs queue put/get calls, but `DebugRuntime.run()` still produces and consumes output in one method, and WebSocket reads only one initial request.
+
+## Scope
+
+This todo covers:
+
+- Add a runtime session entrypoint that starts ChatAgent/EventAgent work and returns `RuntimeQueues`.
+- Keep `DebugRuntime.run()` as a compatibility wrapper for tests and scripts.
+- Add an EventAgent queue consumer task.
+- Preserve provider-valid history ordering when a user message arrives while a tool call is being handled.
+- Split the WebSocket handler into downstream output sending and upstream user-message receiving tasks.
+
+This todo does not cover:
+
+- Multi-session persistence.
+- Multiple simultaneous ChatAgent workers inside one debug session.
+- UI controls for sending a second user message during an active run.
+- Role validation and static asset packaging; those are separate todos.
+
+## Files
+
+- Modify: `src/agent_lab/application/queues.py`
+- Modify: `src/agent_lab/application/runtime.py`
+- Modify: `src/agent_lab/presentation/web.py`
+- Modify: `tests/test_debug_runtime.py`
+- Modify: `tests/test_websocket_api.py`
+- Do not modify unrelated UI styling.
+
+## Design
+
+Add `DebugRuntime.start(request) -> RuntimeQueues`. It should create or reuse `RuntimeQueues`, seed the initial user message into `queues.input`, start background runtime work, and return queues immediately.
+
+`DebugRuntime.run(request)` remains an async iterator by calling `start()` and then consuming `queues.output` until `done` or `error`.
+
+Runtime work should:
+
+- put output payloads onto `queues.output` only;
+- put ChatAgent events onto `queues.events`;
+- run an EventAgent worker that consumes `queues.events` and puts tool replies onto `queues.input`;
+- when waiting for a tool reply, buffer unrelated input messages so the next provider history is `assistant(tool_calls)` -> `tool` -> later `user`.
+
+WebSocket handling should:
+
+- read the first JSON payload as `DebugRunRequest`;
+- start the runtime session;
+- run a downstream task that consumes `queues.output` and sends JSON;
+- run an upstream task that accepts `{"type": "user_message", "content": "..."}` and puts `ChatMessage(role="user", content=...)` into `queues.input`.
+
+## Steps
+
+1. Add failing runtime tests:
+   - `DebugRuntime.start()` returns queues and output can be consumed directly.
+   - User input enqueued during an event handoff is preserved after the matching tool reply.
+2. Add a failing WebSocket test:
+   - send initial request;
+   - receive an event;
+   - send `{"type": "user_message", "content": "follow-up"}`;
+   - assert the second ChatAgent call receives provider-valid ordering.
+3. Refactor `DebugRuntime` to add `start()`, output queue consumption, EventAgent worker, and tool-reply wait logic.
+4. Refactor WebSocket presentation code into separate upstream/downstream tasks for runtimes that expose queue sessions.
+5. Run focused tests:
+
+```bash
+uv run pytest tests/test_debug_runtime.py tests/test_websocket_api.py
+```
+
+6. Run the full suite:
+
+```bash
+uv run pytest
+```
+
+7. Update `docs/plans/todos.md` and this plan with the result, then commit.
+
+## Verification
+
+Expected result:
+
+- Runtime tests prove output queue and event queue have separate consumers.
+- WebSocket tests prove upstream messages can enter the running input queue.
+- Full suite passes.

docs/plans/todos.md

@@ -21,7 +21,7 @@
 - EventAgent tool loading and UI management is covered by todo 10.
 - Prompt/pre-message editing, parameter controls, and reusable prompt sets are covered by todos 3 and 11.
 - Chat-window token, cached-token, TTFT, elapsed-time, and per-round stats are covered by todo 12.
-- No pending todos remain for the original MVP evolution scope.
+- Review follow-up found remaining gaps in real queue boundaries, API validation, packaging, and tool error isolation.
 
 ## Todos
 
@@ -39,3 +39,7 @@
 | 10 | done | `docs/plans/todo-10-tool-registry-management.md` | Replace the single hardcoded EventAgent tool checkbox with a backend tool registry and UI-managed loaded tools. | Tests prove available tools are listed by API and selected tools control EventAgent behavior. |
 | 11 | done | `docs/plans/todo-11-prompt-workspace.md` | Improve prompt/pre-message editing with browser-side persistence and reusable prompt sets. | UI tests or focused JS tests prove prompts persist and can be restored. |
 | 12 | done | `docs/plans/todo-12-round-stats.md` | Move round statistics to structured backend events for token counts, cached tokens, TTFT, elapsed time, and per-turn summaries. | `uv run pytest tests/test_debug_runtime.py tests/test_websocket_api.py`; `uv run pytest`. |
+| 13 | in_progress | `docs/plans/todo-13-real-queue-websocket-loop.md` | Make runtime queues real producer/consumer boundaries and let WebSocket run separate upstream/downstream tasks. | Tests prove output queue can be consumed directly, WS upstream enqueues user input, and event tool replies keep provider-valid order. |
+| 14 | pending | `docs/plans/todo-14-message-role-validation.md` | Reject provider-invalid API message roles and malformed tool replies before network calls. | Tests prove request validation rejects invalid roles and orphan tool messages. |
+| 15 | pending | `docs/plans/todo-15-static-package-data.md` | Include static UI assets in installed package builds. | Build/package inspection proves `index.html`, JS, and CSS are present. |
+| 16 | pending | `docs/plans/todo-16-tool-error-isolation.md` | Convert EventAgent tool handler exceptions into structured tool-result errors instead of aborting the session. | Tests prove a failing tool returns an error payload and the WebSocket run stays structured. |