feat(goal): /goal command & long-running tasks (long_task)

* feat(long-task): add LongTaskTool for multi-step agent tasks Implements a meta-ReAct loop where long-running tasks are broken into sequential subagent steps, each starting fresh with the original goal and progress from the previous step. This prevents context drift when agents work on complex, multi-step tasks. - Extract build_tool_registry() from SubagentManager for reuse - Add run_step() for synchronous subagent execution (no bus announcement) - Add HandoffTool and CompleteTool as signal mechanisms via shared dict - Add LongTaskTool orchestrator with simplified prompt (8 iterations/step) - Register LongTaskTool in main agent loop - Add _extract_handoff_from_messages fallback for robustness * fix(long-task): add debug logging for step-level observability * feat(long-task): major overhaul with structured handoffs, validation, and observability - Structured HandoffState: HandoffTool now accepts files_created, files_modified, next_step_hint, and verification fields instead of a plain string. Progress is passed between steps as structured data. - Completion validation round: After complete() is called, a dedicated validator step runs to verify the claim against the original goal. If validation fails, the task continues rather than returning a false completion. - Dynamic prompt system: 3 Jinja2 templates (step_start, step_middle, step_final) selected based on step number. Final steps get tighter budget and stronger "wrap up" guidance. - Automatic file change tracking: Extracts write_file/edit_file events from tool_events and injects them into the next step's context if the subagent forgot to report them explicitly. - Budget tracking & adaptive strategy: Cumulative token usage is tracked across steps. Per-step tool budget drops from 8 to 4 in the last two steps to force handoff/completion. - Crash retry with graceful degradation: A step that crashes is retried once. Persistent crashes terminate the task and return partial progress. - Full observability hooks for future WebUI integration: - set_hooks() with on_step_start, on_step_complete, on_handoff, on_validation_started, on_validation_passed, on_validation_failed, on_task_complete, on_task_error, and catch-all on_event. - Readable state properties: current_step, total_steps, status, last_handoff, cumulative_usage, goal. - inject_correction() allows external code to send user corrections that are injected into the next step's prompt. - run_step() accepts optional max_iterations for dynamic budget control. All 27 long-task tests and 11 subagent tests pass. * test(long-task): add boundary tests and fix race conditions - Add 7 edge-case tests: validation crash resilience, hook exception safety, mid-run correction injection, FIFO correction ordering, explicit file changes overriding auto-detection, final budget for max_steps=1, and dynamic budget switching boundaries - Fix assertion in test_long_task_completes_after_multiple_handoffs to match exact prompt format - Remove asyncio timing hack from test_state_exposure - Add asyncio.sleep(0) yield in test_inject_correction_during_execution to prevent race between signal injection and step continuation - All 34 tests passing * fix(long-task): address code review findings - Declare _scopes = {"core"} explicitly to prevent recursive nesting in subagent scope - Document fragile coupling in _extract_file_changes: path extraction depends on write_file/edit_file detail format; add debug log for unexpected formats - Align final-template threshold (max_steps - 2) with budget switch threshold - Eliminate hasattr(self, "_state") in _reset_state by initializing in __init__ * fix(long-task): honor final signal and file tracking Co-authored-by: Cursor <cursoragent@cursor.com> * feat(long-task): improve prompt structure and agent contract - Expand LongTaskTool.description to instruct parent agent on goal construction, return value semantics, and how to handle results. - Expand CompleteTool.description to emphasize that the summary IS the final answer returned to the parent agent. - Prefix validated return value with an explicit "final answer" directive to stop parent agent from re-running work. - Redesign step_start.md: Step 1 is now explicitly for exploration, planning, and skeleton-building. complete() is discouraged. - Remove bulky payload debug logging from _emit(); add targeted info/warning/error logs at key state transitions instead. - Add signal_type to HandoffState for cleaner signal detection. * test(long-task): expect wrapped completion message after validation Align assertions with LongTaskTool final return shape on main. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(webui): turn timing strip, latency, and session-switch restore - Agent loop: publish goal_status run/idle for WebSocket turns; attach wall-clock latency_ms on turn_end and persisted assistant metadata. - WebSocket channel: forward goal_status and latency fields to clients. - NanobotClient: track goal_status started_at per chat without requiring onChat; useNanobotStream restores run strip when returning to a chat. - Thread UI: composer/shell viewport hooks for run duration and latency; format helpers and i18n strings. - MessageBubble: drop trailing StreamCursor (layout artifact vs block markdown). - Builtin / tests: model command coverage, websocket and loop tests. Covers multi-session UX and round-trip timing visibility for the WebUI. Co-authored-by: Cursor <cursoragent@cursor.com> * fix: keep message-tool file attachments after canonical history hydrate - MessageTool records per-turn media paths delivered to the active chat. - nanobot.utils.session_attachments stages out-of-media-root files and merges into the last assistant message before save (loop stays a thin call). - WebUI MediaCell: use a signed URL as a real download link when present. Fixes attachments flashing then vanishing on turn_end when paths lived outside get_media_dir (e.g. workspace files). Co-authored-by: Cursor <cursoragent@cursor.com> * feat(webui): agent activity cluster, stable keys, LTR sheen labels - Group reasoning and tool traces in AgentActivityCluster with i18n summaries - Stabilize React list keys for activity clusters (first message id anchor) - Replace background-clip shimmer with overlay sheen for streaming labels - ThreadMessages/MessageList integration and locale strings Co-authored-by: Cursor <cursoragent@cursor.com> * fix(webui): render assistant reasoning with Markdown + deferred stream - Use MarkdownText for ReasoningBubble body (same GFM/KaTeX path as replies) - Apply muted/italic prose tokens so thinking stays visually subordinate - useDeferredValue while reasoningStreaming to ease parser work during deltas - Preload markdown chunk when trace opens; add regression test with preloaded renderer Co-authored-by: Cursor <cursoragent@cursor.com> * fix(webui): default-collapse agent activity cluster while Working Outer fold no longer auto-expands during isTurnStreaming; user opens to see traces. Header sheen and live summary unchanged. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(long_task): cumulative run history, file union, and prompt tuning Inject cross-step summaries and merged file paths into middle/final step templates so chains do not lose early context. Strip the last run-history block when it duplicates Previous Progress to save tokens. Add optional cumulative_prompt_max_chars and cumulative_step_body_max_chars parameters with clamped defaults. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(webui): session switch keeps in-flight thread and replays buffered WS Save the prior chat message list to the per-chat cache in a layout effect when chatId changes (before stale writes could corrupt another chat). Skip one post-switch layout cache tick so we do not snapshot the wrong tab. Buffer inbound events per chat_id when no onChat subscriber is registered (e.g. user focused another session) and drain on resubscribe up to a cap, so streaming deltas are not lost while off-tab. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(webui): snap thread scroll to bottom on session open (no smooth glide) Use scroll-behavior auto on the viewport, instant programmatic scroll when following new messages and on scrollToBottomSignal. Keep smooth only for the explicit scroll-to-bottom button. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(webui): respect manual scroll-up after opening a session Track when the user leaves the bottom with a ref and skip ResizeObserver and deferred bottom snaps until they return or the conversation is reset. Remove the time-based force-bottom window that overrode atBottom. Multi-frame scrollToBottom honours the same guard unless force (scroll button). Co-authored-by: Cursor <cursoragent@cursor.com> * Publish long_task UI snapshots on outbound metadata - Add OUTBOUND_META_AGENT_UI (_agent_ui) for channel-agnostic structured state - LongTaskTool publishes {kind: long_task, data: snapshot} on the bus with _progress - WebSocket send forwards metadata as agent_ui for WebUI clients - Tests for bus payload, WS frame, and progress assertions - Fix loop progress tests: ignore _goal_status in streaming final filter and avoid brittle outbound[-1] ordering after goal status idle messages Co-authored-by: Cursor <cursoragent@cursor.com> * feat: WebUI long_task activity card and resilient history merge Add optional ui_summary to the long_task tool for one-line UI labels. Stream long_task agent_ui into a dedicated message row with timeline, markdown peek, and a right sheet for details. Merge canonical history after turn_end while re-inserting long_task rows before the final assistant reply. Collapse duplicate task_start/step_start steps in the timeline and extend i18n. Co-authored-by: Cursor <cursoragent@cursor.com> * refactor: align long_task with thread_goal and drop orchestrator UI - Persist sustained objectives via session metadata (long_task / complete_goal); no subagent wiring or tool-driven agent_ui payloads.\n- Remove WebUI long-task activity UI, types, and translations; history merge preserves trace replay only, with legacy long_task rows normalized to traces.\n- Drop long_task prompt templates and get_long_task_run_dir; add webui thread disk helper for gateway persistence tests. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(agent): thread goal runtime context, tools, and skill - Add thread_goal_state helper and mirror active objectives into Runtime Context - Wire loop/context/memory/events as needed for goal metadata in turns - Expand long_task / complete_goal semantics (pivot/cancel/honest recap) - Add always-on thread-goal SKILL.md; align /goal command prompt - Tests for context builder and thread goal state - Remove unused webui ChatPane component Co-authored-by: Cursor <cursoragent@cursor.com> * feat(thread-goal): add websocket snapshot helper and publish goal updates from long_task Introduce thread_goal_ws_blob for bounded JSON snapshots, attach snapshots to websocket turn_end metadata in AgentLoop, and let long_task fan-out dedicated thread_goal frames on the websocket channel after persisting session metadata. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(channels): websocket thread_goal frames, turn_end replay, and session API scrub for subagent inject Emit thread_goal events and optional thread_goal on turn_end; scrub persisted subagent announce blobs on GET /api/sessions/.../messages and shorten session list previews so WebUI does not surface full Task/Summarize scaffolding. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(webui): merge ephemeral traces per user turn when reconciling canonical history Preserve disk/live trace rows inside the matching user–assistant segment instead of stacking every trace before the final assistant reply (fixes inflated tool counts after refresh or session switch). Co-authored-by: Cursor <cursoragent@cursor.com> * feat(webui): show assistant reply copy only on the last slice before the next user turn Avoid duplicate copy affordances on intermediate assistant bubbles that precede more agent activity in the same turn (tools or further assistant text). Co-authored-by: Cursor <cursoragent@cursor.com> * feat(webui): thread_goal stream plumbing, composer goal strip, sky glow, and client-side subagent scrub projection Track thread_goal and turn_goal snapshots in NanobotClient, hydrate React state from thread_goal frames and turn_end, surface objective/elapsed in the composer, add breathing sky halo CSS while goals are active, mirror server scrub logic on history hydration and webui_thread snapshots, and extend tests/client mocks. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(channels): add Slack Socket Mode connect timeout with actionable timeout errors Abort hung websockets.connect handshakes after a bounded wait, log REST-vs-WSS guidance, surface RuntimeError to channel startup, and log successful WSS setup. Co-authored-by: Cursor <cursoragent@cursor.com> * webui: expand thread goal in composer bottom sheet Add ChevronUp control on the run/goal strip that opens a bottom Sheet with full ui_summary and objective. Inline preview logic in RunElapsedStrip, add i18n strings across locales, and a composer unit test. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(webui): widen dedupeToolCallsForUi input for session API typing fetchSessionMessages types tool_calls as unknown; accept unknown so tsc build passes when passing message.tool_calls through. Co-authored-by: Cursor <cursoragent@cursor.com> * refactor(agent): extract WebSocket turn run status to webui_turn_helpers * refactor(skills): rename thread-goal to long-task and document idempotent goals * feat(skills): rename sustained-goal skill to long-goal and tighten long_task guidance * chore: remove unused subagent/context/router helpers * feat(session): rename sustained goal to goal_state and align WS/WebUI - Move helpers from agent/thread_goal_state to session/goal_state: GOAL_STATE_KEY, goal_state_runtime_lines, goal_state_ws_blob, parse_goal_state. - Session metadata now uses "goal_state"; still read legacy "thread_goal"; long_task writes drop the legacy key after save. - WebSocket: event/field goal_state, _goal_state_sync; turn_end carries goal_state; accept legacy _thread_goal_sync/thread_goal inbound metadata for dispatch. - WebUI: GoalStateWsPayload, goalState hook/client props, i18n keys goalState*. - Runtime Context copy uses "Goal (active):" instead of "Thread goal". * feat(agent): stream Anthropic thinking deltas and fix stream idle timeout * refactor(webui): transcript jsonl as sole timeline source * fix(agent): reject mismatched WS message chat_id and stream reasoning deltas * feat(webui): hydrate sustained goal and run timer after websocket subscribe * chore(webui,websocket): remove unused fetch helpers and legacy thread_goal WS paths * Raise default max_tokens and context window in agent schema. Align AgentDefaults and ModelPresetConfig with typical Claude-scale usage (32k completion budget, 256k context window) and update migration tests. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(gateway): bootstrap prefers in-memory model; clarify websocket naming * fix(websocket): websocket _handle_message passes is_dm; refresh /status test expectations --------- Co-authored-by: chengyongru <2755839590@qq.com> Co-authored-by: chengyongru <chengyongru.ai@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-16 01:14:11 +08:00
parent 2d17a095dc
commit 1c2ea1aad2
99 changed files with 4886 additions and 848 deletions
@@ -17,6 +17,7 @@ import shutil
 import ssl
 import time
 import uuid
+from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Self
 from urllib.parse import parse_qs, unquote, urlparse
@@ -29,17 +30,22 @@ from websockets.exceptions import ConnectionClosed
 from websockets.http11 import Request as WsRequest
 from websockets.http11 import Response

-from nanobot.bus.events import OutboundMessage
+from nanobot.bus.events import OUTBOUND_META_AGENT_UI, OutboundMessage
 from nanobot.bus.queue import MessageBus
 from nanobot.channels.base import BaseChannel
 from nanobot.command.builtin import builtin_command_palette
 from nanobot.config.paths import get_media_dir
 from nanobot.config.schema import Base
+from nanobot.session.goal_state import goal_state_ws_blob
 from nanobot.utils.helpers import safe_filename
 from nanobot.utils.media_decode import (
    FileSizeExceeded,
    save_base64_data_url,
 )
+from nanobot.utils.subagent_channel_display import scrub_subagent_messages_for_channel
+from nanobot.utils.webui_thread_disk import delete_webui_thread
+from nanobot.utils.webui_transcript import append_transcript_object, build_webui_thread_response
+from nanobot.utils.webui_turn_helpers import websocket_turn_wall_started_at

 if TYPE_CHECKING:
    from nanobot.session.manager import SessionManager
@@ -152,7 +158,7 @@ def publish_runtime_model_update(
    model: str,
    model_preset: str | None,
 ) -> None:
-    """Publish a WebUI runtime-model update onto the outbound bus."""
+    """Enqueue a runtime model snapshot for websocket subscribers (fan-out in-channel)."""
    bus.outbound.put_nowait(OutboundMessage(
        channel="websocket",
        chat_id="*",
@@ -165,18 +171,35 @@ def publish_runtime_model_update(
    ))


-def _read_webui_model_name() -> str | None:
-    """Return the resolved startup model for readonly WebUI display."""
+def _default_model_name_from_config() -> str | None:
+    """Resolved model string from on-disk config (bootstrap fallback)."""
    try:
        from nanobot.config.loader import load_config

        model = load_config().resolve_preset().model.strip()
        return model or None
    except Exception as e:
-        logger.debug("webui bootstrap could not load model name: {}", e)
+        logger.debug("bootstrap model_name could not load from config: {}", e)
        return None


+def _resolve_bootstrap_model_name(
+    runtime_name: Callable[[], str | None] | None,
+) -> str | None:
+    """Prefer an in-process resolver (e.g. AgentLoop); else config-derived default."""
+    if runtime_name is not None:
+        try:
+            raw = runtime_name()
+        except Exception as e:
+            logger.debug("bootstrap runtime model resolver failed: {}", e)
+        else:
+            if isinstance(raw, str):
+                stripped = raw.strip()
+                if stripped:
+                    return stripped
+    return _default_model_name_from_config()
+
+
 def _parse_request_path(path_with_query: str) -> tuple[str, dict[str, list[str]]]:
    """Parse normalized path and query parameters in one pass."""
    parsed = urlparse("ws://x" + path_with_query)
@@ -436,6 +459,7 @@ class WebSocketChannel(BaseChannel):
        *,
        session_manager: "SessionManager | None" = None,
        static_dist_path: Path | None = None,
+        runtime_model_name: Callable[[], str | None] | None = None,
    ):
        if isinstance(config, dict):
            config = WebSocketConfig.model_validate(config)
@@ -449,7 +473,7 @@ class WebSocketChannel(BaseChannel):
        self._conn_default: dict[Any, str] = {}
        # Single-use tokens consumed at WebSocket handshake.
        self._issued_tokens: dict[str, float] = {}
-        # Multi-use tokens for the embedded webui's REST surface; checked but not consumed.
+        # Multi-use tokens for HTTP routes served beside WS; checked but not consumed.
        self._api_tokens: dict[str, float] = {}
        self._stop_event: asyncio.Event | None = None
        self._server_task: asyncio.Task[None] | None = None
@@ -457,6 +481,7 @@ class WebSocketChannel(BaseChannel):
        self._static_dist_path: Path | None = (
            static_dist_path.resolve() if static_dist_path is not None else None
        )
+        self._runtime_model_name = runtime_model_name
        # Process-local secret used to HMAC-sign media URLs. The signed URL is
        # the capability — anyone who holds a valid URL can fetch that one
        # file, nothing else. The secret regenerates on restart so links
@@ -482,6 +507,36 @@ class WebSocketChannel(BaseChannel):
                self._subs.pop(cid, None)
        self._conn_default.pop(connection, None)

+    async def _maybe_push_active_goal_state(self, chat_id: str) -> None:
+        """Replay an active sustained goal from session metadata after *chat_id* is subscribed.
+
+        Goal metadata lives on the session JSONL and survives gateway restarts, but
+        connected clients normally see it via ``goal_state`` / ``turn_end`` frames.
+        Pushing here makes refresh + reconnect restore the strip without a new model turn.
+        """
+        if self._session_manager is None:
+            return
+        row = self._session_manager.read_session_file(f"websocket:{chat_id}")
+        meta = row.get("metadata", {}) if isinstance(row, dict) else {}
+        if not isinstance(meta, dict):
+            meta = {}
+        blob = goal_state_ws_blob(meta)
+        if not blob.get("active"):
+            return
+        await self.send_goal_state(chat_id, blob)
+
+    async def _maybe_push_turn_run_wall_clock(self, chat_id: str) -> None:
+        """Replay ``goal_status: running`` when a turn is still active (same-process refresh)."""
+        t0 = websocket_turn_wall_started_at(chat_id)
+        if t0 is None:
+            return
+        await self.send_goal_status(chat_id, "running", started_at=t0)
+
+    async def _hydrate_after_subscribe(self, chat_id: str) -> None:
+        """Replay goal/run strip state after subscribe (same-process refresh)."""
+        await self._maybe_push_active_goal_state(chat_id)
+        await self._maybe_push_turn_run_wall_clock(chat_id)
+
    async def _send_event(self, connection: Any, event: str, **fields: Any) -> None:
        """Send a control event (attached, error, ...) to a single connection."""
        payload: dict[str, Any] = {"event": event}
@@ -575,11 +630,11 @@ class WebSocketChannel(BaseChannel):
            if got == issue_expected:
                return self._handle_token_issue_http(connection, request)

-        # 2. WebUI bootstrap: mints tokens for the embedded UI.
+        # 2. Bootstrap (`/webui/bootstrap`): mint WS/API tokens + shared session metadata.
        if got == "/webui/bootstrap":
-            return self._handle_webui_bootstrap(connection, request)
+            return self._handle_bootstrap(connection, request)

-        # 3. REST surface for the embedded UI.
+        # 3. REST handlers co-located with this channel (sessions, settings, …).
        if got == "/api/sessions":
            return self._handle_sessions_list(request)

@@ -602,6 +657,10 @@ class WebSocketChannel(BaseChannel):
        if m:
            return self._handle_session_messages(request, m.group(1))

+        m = re.match(r"^/api/sessions/([^/]+)/webui-thread$", got)
+        if m:
+            return self._handle_webui_thread_get(request, m.group(1))
+
        # NOTE: websockets' HTTP parser only accepts GET, so we cannot expose a
        # true ``DELETE`` verb. The action is folded into the path instead.
        m = re.match(r"^/api/sessions/([^/]+)/delete$", got)
@@ -659,7 +718,7 @@ class WebSocketChannel(BaseChannel):
            if now > expiry:
                self._api_tokens.pop(token_key, None)

-    def _handle_webui_bootstrap(self, connection: Any, request: Any) -> Response:
+    def _handle_bootstrap(self, connection: Any, request: Any) -> Response:
        # When a secret is configured (token_issue_secret or static token),
        # validate it regardless of source IP.  This secures deployments
        # behind a reverse proxy where all connections appear as localhost.
@@ -669,7 +728,7 @@ class WebSocketChannel(BaseChannel):
                return _http_error(401, "Unauthorized")
        elif not _is_localhost(connection):
            # No secret configured: only allow localhost (local dev mode).
-            return _http_error(403, "webui bootstrap is localhost-only")
+            return _http_error(403, "bootstrap is localhost-only")
        # Cap outstanding tokens to avoid runaway growth from a misbehaving client.
        self._purge_expired_issued_tokens()
        self._purge_expired_api_tokens()
@@ -693,7 +752,7 @@ class WebSocketChannel(BaseChannel):
                "token": token,
                "ws_path": self._expected_path(),
                "expires_in": self.config.token_ttl_s,
-                "model_name": _read_webui_model_name(),
+                "model_name": _resolve_bootstrap_model_name(self._runtime_model_name),
            }
        )

@@ -703,10 +762,8 @@ class WebSocketChannel(BaseChannel):
        if self._session_manager is None:
            return _http_error(503, "session manager unavailable")
        sessions = self._session_manager.list_sessions()
-        # The webui is only meaningful for websocket-channel chats — CLI /
-        # Slack / Lark / Discord sessions can't be resumed from the browser,
-        # so leaking them into the sidebar is just noise. Filter to the
-        # ``websocket:`` prefix and strip absolute paths on the way out.
+        # Sidebar/chat listing for WS-backed sessions only — CLI / Slack / etc.
+        # keys are not intended for resume over this HTTP surface.
        cleaned = [
            {k: v for k, v in s.items() if k != "path"}
            for s in sessions
@@ -918,8 +975,8 @@ class WebSocketChannel(BaseChannel):
        return _http_json_response(self._settings_payload(requires_restart=False))

    @staticmethod
-    def _is_webui_session_key(key: str) -> bool:
-        """Return True when *key* belongs to the webui's websocket-only surface."""
+    def _is_websocket_channel_session_key(key: str) -> bool:
+        """True when *key* is a ``websocket:…`` session exposed on this HTTP surface."""
        return key.startswith("websocket:")

    def _handle_session_messages(self, request: WsRequest, key: str) -> Response:
@@ -930,14 +987,16 @@ class WebSocketChannel(BaseChannel):
        decoded_key = _decode_api_key(key)
        if decoded_key is None:
            return _http_error(400, "invalid session key")
-        # The embedded webui only understands websocket-channel sessions. Keep
-        # its read surface aligned with ``/api/sessions`` instead of letting a
-        # caller probe arbitrary CLI / Slack / Lark history by handcrafted URL.
-        if not self._is_webui_session_key(decoded_key):
+        # Only ``websocket:…`` sessions are listed/served here — same boundary as
+        # ``/api/sessions``. Block handcrafted URLs from probing CLI / Slack / etc.
+        if not self._is_websocket_channel_session_key(decoded_key):
            return _http_error(404, "session not found")
        data = self._session_manager.read_session_file(decoded_key)
        if data is None:
            return _http_error(404, "session not found")
+        messages = data.get("messages")
+        if isinstance(messages, list):
+            scrub_subagent_messages_for_channel(messages)
        # Decorate persisted user messages with signed media URLs so the
        # client can render previews. The raw on-disk ``media`` paths are
        # stripped on the way out — they leak server filesystem layout and
@@ -945,6 +1004,74 @@ class WebSocketChannel(BaseChannel):
        self._augment_media_urls(data)
        return _http_json_response(data)

+    def _handle_webui_thread_get(self, request: WsRequest, key: str) -> Response:
+        if not self._check_api_token(request):
+            return _http_error(401, "Unauthorized")
+        decoded_key = _decode_api_key(key)
+        if decoded_key is None:
+            return _http_error(400, "invalid session key")
+        if not self._is_websocket_channel_session_key(decoded_key):
+            return _http_error(404, "session not found")
+        data = build_webui_thread_response(
+            decoded_key,
+            augment_user_media=self._augment_transcript_user_media,
+        )
+        if data is None:
+            return _http_error(404, "webui thread not found")
+        return _http_json_response(data)
+
+    def _try_append_webui_transcript(self, chat_id: str, wire: dict[str, Any]) -> None:
+        sk = f"websocket:{chat_id}"
+        try:
+            dup = json.loads(json.dumps(wire, ensure_ascii=False))
+            append_transcript_object(sk, dup)
+        except (ValueError, TypeError) as e:
+            self.logger.warning("webui transcript append failed: {}", e)
+
+    def _augment_transcript_user_media(self, paths: list[str]) -> list[dict[str, Any]]:
+        out: list[dict[str, Any]] = []
+        for pstr in paths:
+            path = Path(pstr)
+            att = self._sign_or_stage_media_path(path)
+            if att is None:
+                continue
+            mime, _ = mimetypes.guess_type(path.name)
+            kind = "video" if mime and mime.startswith("video/") else "image"
+            out.append(
+                {"kind": kind, "url": att["url"], "name": att.get("name", path.name)},
+            )
+        return out
+
+    async def _handle_message(
+        self,
+        sender_id: str,
+        chat_id: str,
+        content: str,
+        media: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        session_key: str | None = None,
+        is_dm: bool = False,
+    ) -> None:
+        meta = metadata or {}
+        if meta.get("webui"):
+            user_obj: dict[str, Any] = {
+                "event": "user",
+                "chat_id": chat_id,
+                "text": content,
+            }
+            if media:
+                user_obj["media_paths"] = list(media)
+            self._try_append_webui_transcript(chat_id, user_obj)
+        await super()._handle_message(
+            sender_id,
+            chat_id,
+            content,
+            media,
+            metadata,
+            session_key,
+            is_dm,
+        )
+
    def _augment_media_urls(self, payload: dict[str, Any]) -> None:
        """Mutate *payload* in place: each message's ``media`` path list is
        replaced by a parallel ``media_urls`` list of signed fetch URLs.
@@ -983,7 +1110,7 @@ class WebSocketChannel(BaseChannel):
        The URL is self-authenticating: the signature binds the payload to
        this process's ``_media_secret``, so only paths we chose to sign can
        be fetched. The returned path is relative to the server origin; the
-        client joins it against the existing webui base.
+        client joins it against this server's HTTP origin (same host as WS).
        """
        try:
            media_root = get_media_dir().resolve()
@@ -1079,12 +1206,12 @@ class WebSocketChannel(BaseChannel):
        decoded_key = _decode_api_key(key)
        if decoded_key is None:
            return _http_error(400, "invalid session key")
-        # Same boundary as ``_handle_session_messages``: the webui may only
-        # mutate websocket sessions, and deletion really does unlink the local
-        # JSONL, so keep the blast radius narrow and explicit.
-        if not self._is_webui_session_key(decoded_key):
+        # Same boundary as ``_handle_session_messages``: mutations apply only to
+        # websocket-channel sessions; deletion unlinks local JSONL — keep scope narrow.
+        if not self._is_websocket_channel_session_key(decoded_key):
            return _http_error(404, "session not found")
        deleted = self._session_manager.delete_session(decoded_key)
+        delete_webui_thread(decoded_key)
        return _http_json_response({"deleted": bool(deleted)})

    def _serve_static(self, request_path: str) -> Response | None:
@@ -1232,6 +1359,7 @@ class WebSocketChannel(BaseChannel):
            # Register only after ready is successfully sent to avoid out-of-order sends
            self._conn_default[connection] = default_chat_id
            self._attach(connection, default_chat_id)
+            await self._hydrate_after_subscribe(default_chat_id)

            async for raw in connection:
                if isinstance(raw, bytes):
@@ -1344,6 +1472,7 @@ class WebSocketChannel(BaseChannel):
            new_id = str(uuid.uuid4())
            self._attach(connection, new_id)
            await self._send_event(connection, "attached", chat_id=new_id)
+            await self._hydrate_after_subscribe(new_id)
            return
        if t == "attach":
            cid = envelope.get("chat_id")
@@ -1352,6 +1481,7 @@ class WebSocketChannel(BaseChannel):
                return
            self._attach(connection, cid)
            await self._send_event(connection, "attached", chat_id=cid)
+            await self._hydrate_after_subscribe(cid)
            return
        if t == "message":
            cid = envelope.get("chat_id")
@@ -1387,6 +1517,7 @@ class WebSocketChannel(BaseChannel):

            # Auto-attach on first use so clients can one-shot without a separate attach.
            self._attach(connection, cid)
+            await self._hydrate_after_subscribe(cid)
            metadata: dict[str, Any] = {"remote": getattr(connection, "remote_address", None)}
            if envelope.get("webui") is True:
                metadata["webui"] = True
@@ -1452,14 +1583,34 @@ class WebSocketChannel(BaseChannel):
                msg.metadata.get("_progress")
                or msg.metadata.get("_turn_end")
                or msg.metadata.get("_session_updated")
+                or msg.metadata.get("_goal_status")
+                or msg.metadata.get("_goal_state_sync")
            ):
                self.logger.debug("no active subscribers for chat_id={}", msg.chat_id)
            else:
                self.logger.warning("no active subscribers for chat_id={}", msg.chat_id)
            return
+        if msg.metadata.get("_goal_state_sync"):
+            blob = msg.metadata.get("goal_state")
+            await self.send_goal_state(msg.chat_id, blob if isinstance(blob, dict) else {"active": False})
+            return
+        if msg.metadata.get("_goal_status"):
+            status = msg.metadata.get("goal_status")
+            if status in ("running", "idle"):
+                started_raw = msg.metadata.get("started_at", msg.metadata.get("goal_started_at"))
+                await self.send_goal_status(
+                    msg.chat_id,
+                    status,
+                    started_at=float(started_raw) if isinstance(started_raw, int | float) else None,
+                )
+            return
        # Signal that the agent has fully finished processing the current turn.
        if msg.metadata.get("_turn_end"):
-            await self.send_turn_end(msg.chat_id)
+            lat = msg.metadata.get("latency_ms")
+            lat_i = int(lat) if isinstance(lat, (int, float)) else None
+            gs = msg.metadata.get("goal_state")
+            gs_blob = gs if isinstance(gs, dict) else None
+            await self.send_turn_end(msg.chat_id, latency_ms=lat_i, goal_state=gs_blob)
            return
        if msg.metadata.get("_session_updated"):
            await self.send_session_updated(msg.chat_id)
@@ -1481,8 +1632,14 @@ class WebSocketChannel(BaseChannel):
                payload["media_urls"] = urls
        if msg.reply_to:
            payload["reply_to"] = msg.reply_to
+        lat = msg.metadata.get("latency_ms")
+        if isinstance(lat, (int, float)):
+            payload["latency_ms"] = int(lat)
        if msg.metadata.get("_tool_events"):
            payload["tool_events"] = msg.metadata["_tool_events"]
+        agent_ui = msg.metadata.get(OUTBOUND_META_AGENT_UI)
+        if agent_ui is not None:
+            payload["agent_ui"] = agent_ui
        # Mark intermediate agent breadcrumbs (tool-call hints, generic
        # progress strings) so WS clients can render them as subordinate
        # trace rows rather than conversational replies.
@@ -1490,6 +1647,7 @@ class WebSocketChannel(BaseChannel):
            payload["kind"] = "tool_hint"
        elif msg.metadata.get("_progress"):
            payload["kind"] = "progress"
+        self._try_append_webui_transcript(msg.chat_id, payload)
        raw = json.dumps(payload, ensure_ascii=False)
        for connection in conns:
            await self._safe_send_to(connection, raw, label=" ")
@@ -1501,7 +1659,7 @@ class WebSocketChannel(BaseChannel):
        metadata: dict[str, Any] | None = None,
    ) -> None:
        """Push one chunk of model reasoning. Mirrors ``send_delta`` shape so
-        WebUI receives a stream that opens, updates in place, and closes —
+        clients receive a stream that opens, updates in place, and closes —
        rendered above the active assistant bubble with a shimmer header
        until the matching ``reasoning_end`` arrives.
        """
@@ -1517,6 +1675,7 @@ class WebSocketChannel(BaseChannel):
        stream_id = meta.get("_stream_id")
        if stream_id is not None:
            body["stream_id"] = stream_id
+        self._try_append_webui_transcript(chat_id, body)
        raw = json.dumps(body, ensure_ascii=False)
        for connection in conns:
            await self._safe_send_to(connection, raw, label=" reasoning ")
@@ -1538,6 +1697,7 @@ class WebSocketChannel(BaseChannel):
        stream_id = meta.get("_stream_id")
        if stream_id is not None:
            body["stream_id"] = stream_id
+        self._try_append_webui_transcript(chat_id, body)
        raw = json.dumps(body, ensure_ascii=False)
        for connection in conns:
            await self._safe_send_to(connection, raw, label=" reasoning_end ")
@@ -1562,20 +1722,64 @@ class WebSocketChannel(BaseChannel):
            }
        if meta.get("_stream_id") is not None:
            body["stream_id"] = meta["_stream_id"]
+        self._try_append_webui_transcript(chat_id, body)
        raw = json.dumps(body, ensure_ascii=False)
        for connection in conns:
            await self._safe_send_to(connection, raw, label=" stream ")

-    async def send_turn_end(self, chat_id: str) -> None:
+    async def send_turn_end(
+        self,
+        chat_id: str,
+        latency_ms: int | None = None,
+        *,
+        goal_state: dict[str, Any] | None = None,
+    ) -> None:
        """Signal that the agent has fully finished processing the current turn."""
        conns = list(self._subs.get(chat_id, ()))
        if not conns:
            return
        body: dict[str, Any] = {"event": "turn_end", "chat_id": chat_id}
+        if latency_ms is not None:
+            body["latency_ms"] = int(latency_ms)
+        if goal_state is not None:
+            body["goal_state"] = goal_state
+        self._try_append_webui_transcript(chat_id, body)
        raw = json.dumps(body, ensure_ascii=False)
        for connection in conns:
            await self._safe_send_to(connection, raw, label=" turn_end ")

+    async def send_goal_state(self, chat_id: str, blob: dict[str, Any]) -> None:
+        """Push persisted goal-state snapshot for *chat_id* (multi-chat isolation)."""
+        conns = list(self._subs.get(chat_id, ()))
+        if not conns:
+            return
+        body = {"event": "goal_state", "chat_id": chat_id, "goal_state": blob}
+        raw = json.dumps(body, ensure_ascii=False)
+        for connection in conns:
+            await self._safe_send_to(connection, raw, label=" goal_state ")
+
+    async def send_goal_status(
+        self,
+        chat_id: str,
+        status: str,
+        *,
+        started_at: float | None = None,
+    ) -> None:
+        """Notify subscribed clients that a turn started or finished (wall-clock hint)."""
+        conns = list(self._subs.get(chat_id, ()))
+        if not conns:
+            return
+        body: dict[str, Any] = {
+            "event": "goal_status",
+            "chat_id": chat_id,
+            "status": status,
+        }
+        if status == "running" and started_at is not None:
+            body["started_at"] = started_at
+        raw = json.dumps(body, ensure_ascii=False)
+        for connection in conns:
+            await self._safe_send_to(connection, raw, label=" goal_status ")
+
    async def send_session_updated(self, chat_id: str) -> None:
        """Notify clients that session metadata changed outside the main turn."""
        conns = list(self._subs.get(chat_id, ()))
@@ -1592,7 +1796,7 @@ class WebSocketChannel(BaseChannel):
        model_name: Any,
        model_preset: Any = None,
    ) -> None:
-        """Broadcast runtime model changes to all active WebUI clients."""
+        """Broadcast runtime model changes to every open websocket connection."""
        conns = list(self._conn_chats)
        if not conns or not isinstance(model_name, str) or not model_name.strip():
            return