@nextclaw/ui 0.11.22 → 0.12.0

package/src/components/chat/containers/chat-message-list.container.tsx

@@ -1,6 +1,7 @@
 import { useMemo } from "react";
 import type { NcpMessage } from "@nextclaw/ncp";
 import {
+  type ChatToolActionViewModel,
   type ChatMessageViewModel,
   ChatMessageList,
 } from "@nextclaw/agent-chat-ui";
@@ -11,6 +12,7 @@ import {
 } from "@/components/chat/adapters/chat-message.adapter";
 import { readInlineTokensFromMetadata } from "@/components/chat/chat-inline-token.utils";
 import { adaptNcpMessageToUiMessage } from "@/components/chat/ncp/ncp-session-adapter";
+import { AgentIdentityAvatar } from "@/components/common/agent-identity";
 import { useI18n } from "@/components/providers/I18nProvider";
 import { formatDateTime, t } from "@/lib/i18n";
 
@@ -18,6 +20,7 @@ type ChatMessageListContainerProps = {
   messages: readonly NcpMessage[];
   isSending: boolean;
   className?: string;
+  onToolAction?: (action: ChatToolActionViewModel) => void;
 };
 
 const messageViewModelCache = new WeakMap<
@@ -69,6 +72,7 @@ export function ChatMessageListContainer({
   messages: rawMessages,
   isSending,
   className,
+  onToolAction,
 }: ChatMessageListContainerProps) {
   const { language } = useI18n();
   const texts = useMemo<ChatMessageAdapterTexts>(
@@ -125,6 +129,13 @@ export function ChatMessageListContainer({
       hasAssistantDraft={hasAssistantDraft}
       className={className}
       texts={messageTexts}
+      onToolAction={onToolAction}
+      renderToolAgent={(agentId) => (
+        <AgentIdentityAvatar
+          agentId={agentId}
+          className="h-4 w-4 shrink-0"
+        />
+      )}
     />
   );
 }

package/src/components/chat/ncp/NcpChatPage.tsx

@@ -1,32 +1,44 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { NcpHttpAgentClientEndpoint } from '@nextclaw/ncp-http-agent-client';
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import {
   buildNcpRequestEnvelope,
-  useHydratedNcpAgent,
-  type NcpConversationSeed
-} from '@nextclaw/ncp-react';
-import { useLocation, useNavigate, useParams } from 'react-router-dom';
-import { API_BASE } from '@/api/api-base';
-import { fetchNcpSessionMessages } from '@/api/ncp-session';
-import { ChatPageLayout, type ChatPageProps, useChatSessionSync } from '@/components/chat/chat-page-shell';
-import { sessionDisplayName } from '@/components/chat/chat-session-display';
-import { buildInlineSkillTokensFromComposer, CHAT_UI_INLINE_TOKENS_METADATA_KEY } from '@/components/chat/chat-inline-token.utils';
-import { createNcpAppClientFetch } from '@/components/chat/ncp/ncp-app-client-fetch';
-import { parseSessionKeyFromRoute, resolveAgentIdFromSessionKey } from '@/components/chat/chat-session-route';
-import { useNcpChatPageData } from '@/components/chat/ncp/ncp-chat-page-data';
-import { NcpChatPresenter } from '@/components/chat/ncp/ncp-chat.presenter';
-import { createNcpSessionId } from '@/components/chat/ncp/ncp-session-adapter';
-import { ChatPresenterProvider } from '@/components/chat/presenter/chat-presenter-context';
-import type { ResumeRunParams } from '@/components/chat/chat-stream/types';
-import { useChatInputStore } from '@/components/chat/stores/chat-input.store';
-import { useChatSessionListStore } from '@/components/chat/stores/chat-session-list.store';
-import { resolveSessionTypeLabel } from '@/components/chat/useChatSessionTypeState';
-import { useConfirmDialog } from '@/hooks/useConfirmDialog';
-import { normalizeRequestedSkills } from '@/lib/chat-runtime-utils';
-import { getSessionProjectName, normalizeSessionProjectRootValue } from '@/lib/session-project/session-project.utils';
-import { appClient } from '@/transport';
+} from "@nextclaw/ncp-react";
+import { useLocation, useNavigate, useParams } from "react-router-dom";
+import {
+  ChatPageLayout,
+  type ChatPageProps,
+  useChatSessionSync,
+} from "@/components/chat/chat-page-shell";
+import {
+  buildInlineSkillTokensFromComposer,
+  CHAT_UI_INLINE_TOKENS_METADATA_KEY,
+} from "@/components/chat/chat-inline-token.utils";
+import {
+  parseSessionKeyFromRoute,
+} from "@/components/chat/chat-session-route";
+import { useNcpChatPageData } from "@/components/chat/ncp/ncp-chat-page-data";
+import { NcpChatPresenter } from "@/components/chat/ncp/ncp-chat.presenter";
+import { createNcpSessionId } from "@/components/chat/ncp/ncp-session-adapter";
+import { useNcpSessionConversation } from "@/components/chat/ncp/session-conversation/use-ncp-session-conversation";
+import { useNcpChatDerivedState, useNcpChatSnapshotSync } from "@/components/chat/ncp/page/ncp-chat-derived-state";
+import { ChatPresenterProvider } from "@/components/chat/presenter/chat-presenter-context";
+import type { ResumeRunParams } from "@/components/chat/chat-stream/types";
+import { useChatInputStore } from "@/components/chat/stores/chat-input.store";
+import { useChatSessionListStore } from "@/components/chat/stores/chat-session-list.store";
+import { useConfirmDialog } from "@/hooks/useConfirmDialog";
+import { useAgents } from "@/hooks/agents/useAgents";
+import { normalizeRequestedSkills } from "@/lib/chat-runtime-utils";
+import {
+  getSessionProjectName,
+  normalizeSessionProjectRootValue,
+} from "@/lib/session-project/session-project.utils";
 
 export function buildNcpSendMetadata(payload: {
+  agentId?: string;
   model?: string;
   thinkingLevel?: string;
   sessionType?: string;
@@ -46,6 +58,9 @@ export function buildNcpSendMetadata(payload: {
   if (payload.sessionType?.trim()) {
     metadata.session_type = payload.sessionType.trim();
   }
+  if (payload.agentId?.trim()) {
+    metadata.agent_id = payload.agentId.trim();
+  }
   const projectRoot = normalizeSessionProjectRootValue(payload.projectRoot);
   if (projectRoot) {
     metadata.project_root = projectRoot;
@@ -63,37 +78,49 @@ export function buildNcpSendMetadata(payload: {
   return metadata;
 }
 
-function isMissingNcpSessionError(error: unknown): boolean {
-  if (!(error instanceof Error)) {
-    return false;
-  }
-  return error.message.includes('ncp session not found:');
-}
-
 export function NcpChatPage({ view }: ChatPageProps) {
   const [presenter] = useState(() => new NcpChatPresenter());
-  const [draftSessionId, setDraftSessionId] = useState(() => createNcpSessionId());
+  const [draftSessionId, setDraftSessionId] = useState(() =>
+    createNcpSessionId(),
+  );
   const query = useChatSessionListStore((state) => state.snapshot.query);
-  const selectedSessionKey = useChatSessionListStore((state) => state.snapshot.selectedSessionKey);
-  const selectedAgentId = useChatSessionListStore((state) => state.snapshot.selectedAgentId);
-  const pendingSessionType = useChatInputStore((state) => state.snapshot.pendingSessionType);
-  const pendingProjectRoot = useChatInputStore((state) => state.snapshot.pendingProjectRoot);
-  const pendingProjectRootSessionKey = useChatInputStore((state) => state.snapshot.pendingProjectRootSessionKey);
-  const currentSelectedModel = useChatInputStore((state) => state.snapshot.selectedModel);
+  const selectedSessionKey = useChatSessionListStore(
+    (state) => state.snapshot.selectedSessionKey,
+  );
+  const selectedAgentId = useChatSessionListStore(
+    (state) => state.snapshot.selectedAgentId,
+  );
+  const pendingSessionType = useChatInputStore(
+    (state) => state.snapshot.pendingSessionType,
+  );
+  const pendingProjectRoot = useChatInputStore(
+    (state) => state.snapshot.pendingProjectRoot,
+  );
+  const pendingProjectRootSessionKey = useChatInputStore(
+    (state) => state.snapshot.pendingProjectRootSessionKey,
+  );
+  const agentsQuery = useAgents();
+  const currentSelectedModel = useChatInputStore(
+    (state) => state.snapshot.selectedModel,
+  );
   const { confirm, ConfirmDialog } = useConfirmDialog();
   const location = useLocation();
   const navigate = useNavigate();
-  const { sessionId: routeSessionIdParam } = useParams<{ sessionId?: string }>();
+  const { sessionId: routeSessionIdParam } = useParams<{
+    sessionId?: string;
+  }>();
   const threadRef = useRef<HTMLDivElement | null>(null);
   const selectedSessionKeyRef = useRef<string | null>(selectedSessionKey);
-  const sessionStreamAttachInFlightRef = useRef(false);
   const routeSessionKey = useMemo(
     () => parseSessionKeyFromRoute(routeSessionIdParam),
-    [routeSessionIdParam]
+    [routeSessionIdParam],
   );
   const sessionKey = selectedSessionKey ?? draftSessionId;
-  const hasSessionProjectRootOverride = pendingProjectRootSessionKey === sessionKey;
-  const sessionProjectRootOverride = hasSessionProjectRootOverride ? pendingProjectRoot : undefined;
+  const hasSessionProjectRootOverride =
+    pendingProjectRootSessionKey === sessionKey;
+  const sessionProjectRootOverride = hasSessionProjectRootOverride
+    ? pendingProjectRoot
+    : undefined;
   const {
     sessionSkillsQuery,
     isProviderStateResolved,
@@ -106,7 +133,7 @@ export function NcpChatPage({ view }: ChatPageProps) {
     selectedSessionType,
     canEditSessionType,
     sessionTypeUnavailable,
-    sessionTypeUnavailableMessage
+    sessionTypeUnavailableMessage,
   } = useNcpChatPageData({
     query,
     sessionKey,
@@ -115,47 +142,11 @@ export function NcpChatPage({ view }: ChatPageProps) {
     pendingSessionType,
     setPendingSessionType: presenter.chatInputManager.setPendingSessionType,
     setSelectedModel: presenter.chatInputManager.setSelectedModel,
-    setSelectedThinkingLevel: presenter.chatInputManager.setSelectedThinkingLevel
+    setSelectedThinkingLevel:
+      presenter.chatInputManager.setSelectedThinkingLevel,
   });
 
-  const sessionSummariesRef = useRef(sessionSummaries);
-  useEffect(() => {
-    sessionSummariesRef.current = sessionSummaries;
-  }, [sessionSummaries]);
-
-  const [ncpClient] = useState(
-    () =>
-      new NcpHttpAgentClientEndpoint({
-      baseUrl: API_BASE,
-      basePath: '/api/ncp/agent',
-      fetchImpl: createNcpAppClientFetch()
-      })
-  );
-
-  const loadSeed = useCallback(async (sessionId: string, signal: AbortSignal): Promise<NcpConversationSeed> => {
-    signal.throwIfAborted();
-    let history: Awaited<ReturnType<typeof fetchNcpSessionMessages>> | null = null;
-    try {
-      history = await fetchNcpSessionMessages(sessionId, 300);
-    } catch (error) {
-      if (!isMissingNcpSessionError(error)) {
-        throw error;
-      }
-    }
-    signal.throwIfAborted();
-
-    const sessionSummary = sessionSummariesRef.current.find((item) => item.sessionId === sessionId) ?? null;
-    return {
-      messages: history?.messages ?? [],
-      status: sessionSummary?.status === 'running' ? 'running' : 'idle'
-    };
-  }, []);
-
-  const agent = useHydratedNcpAgent({
-    sessionId: sessionKey,
-    client: ncpClient,
-    loadSeed
-  });
+  const agent = useNcpSessionConversation(sessionKey);
 
   useEffect(() => {
     presenter.setDraftSessionId(draftSessionId);
@@ -169,43 +160,21 @@ export function NcpChatPage({ view }: ChatPageProps) {
     }
   }, [presenter, selectedSessionKey]);
 
-  const effectiveSessionProjectRoot = hasSessionProjectRootOverride ? pendingProjectRoot : selectedSession?.projectRoot ?? null;
-  const effectiveSessionProjectName = hasSessionProjectRootOverride ? getSessionProjectName(effectiveSessionProjectRoot) : selectedSession?.projectName ?? getSessionProjectName(effectiveSessionProjectRoot);
+  const effectiveSessionProjectRoot = hasSessionProjectRootOverride
+    ? pendingProjectRoot
+    : (selectedSession?.projectRoot ?? null);
+  const effectiveSessionProjectName = hasSessionProjectRootOverride
+    ? getSessionProjectName(effectiveSessionProjectRoot)
+    : (selectedSession?.projectName ??
+      getSessionProjectName(effectiveSessionProjectRoot));
+  const parentSessionId = selectedSession?.parentSessionId ?? null;
 
   const isSending = agent.isSending || agent.isRunning;
   const isAwaitingAssistantOutput = agent.isRunning;
   const canStopCurrentRun = agent.isRunning;
-  const stopDisabledReason = agent.isRunning ? null : '__preparing__';
-  const lastSendError = agent.hydrateError?.message ?? agent.snapshot.error?.message ?? null;
-
-  useEffect(() => {
-    const attachRealtimeSessionStream = () => {
-      if (sessionStreamAttachInFlightRef.current) {
-        return;
-      }
-      if (agent.isHydrating || agent.isRunning || agent.isSending) {
-        return;
-      }
-
-      sessionStreamAttachInFlightRef.current = true;
-      void ncpClient
-        .stream({ sessionId: sessionKey })
-        .catch(() => undefined)
-        .finally(() => {
-          sessionStreamAttachInFlightRef.current = false;
-        });
-    };
-
-    return appClient.subscribe((event) => {
-      if (
-        event.type === 'session.run-status' &&
-        event.payload.sessionKey === sessionKey &&
-        event.payload.status === 'running'
-      ) {
-        attachRealtimeSessionStream();
-      }
-    });
-  }, [agent.isHydrating, agent.isRunning, agent.isSending, ncpClient, sessionKey]);
+  const stopDisabledReason = agent.isRunning ? null : "__preparing__";
+  const lastSendError =
+    agent.hydrateError?.message ?? agent.snapshot.error?.message ?? null;
 
   useEffect(() => {
     presenter.chatStreamActionsManager.bind({
@@ -214,22 +183,23 @@ export function NcpChatPage({ view }: ChatPageProps) {
           return;
         }
         const metadata = buildNcpSendMetadata({
+          agentId: payload.agentId,
           model: payload.model,
           thinkingLevel: payload.thinkingLevel,
           sessionType: payload.sessionType,
           projectRoot:
             payload.sessionKey === pendingProjectRootSessionKey
               ? pendingProjectRoot
-              : selectedSession?.projectRoot ?? null,
+              : (selectedSession?.projectRoot ?? null),
           requestedSkills: payload.requestedSkills,
-          composerNodes: payload.composerNodes
+          composerNodes: payload.composerNodes,
         });
         const envelope = buildNcpRequestEnvelope({
           sessionId: payload.sessionKey,
           text: payload.message,
           attachments: payload.attachments,
           parts: payload.parts,
-          metadata
+          metadata,
         });
         if (!envelope) {
           return;
@@ -241,11 +211,13 @@ export function NcpChatPage({ view }: ChatPageProps) {
             if (payload.composerNodes && payload.composerNodes.length > 0) {
               presenter.chatInputManager.restoreComposerState?.(
                 payload.composerNodes,
-                payload.attachments ?? []
+                payload.attachments ?? [],
               );
             } else {
               presenter.chatInputManager.setDraft((currentDraft) =>
-                currentDraft.trim().length === 0 ? payload.message : currentDraft
+                currentDraft.trim().length === 0
+                  ? payload.message
+                  : currentDraft,
               );
             }
           }
@@ -264,7 +236,7 @@ export function NcpChatPage({ view }: ChatPageProps) {
       resetStreamState: () => {
         selectedSessionKeyRef.current = null;
       },
-      applyHistoryMessages: () => {}
+      applyHistoryMessages: () => {},
     });
   }, [
     agent,
@@ -272,16 +244,20 @@ export function NcpChatPage({ view }: ChatPageProps) {
     pendingProjectRootSessionKey,
     presenter,
     selectedSession?.projectRoot,
-    sessionKey
+    sessionKey,
   ]);
 
   useEffect(() => {
-    if (!selectedSession || pendingProjectRootSessionKey !== selectedSession.key || (selectedSession.projectRoot ?? null) !== pendingProjectRoot) {
+    if (
+      !selectedSession ||
+      pendingProjectRootSessionKey !== selectedSession.key ||
+      (selectedSession.projectRoot ?? null) !== pendingProjectRoot
+    ) {
       return;
     }
     useChatInputStore.getState().setSnapshot({
       pendingProjectRoot: null,
-      pendingProjectRootSessionKey: null
+      pendingProjectRootSessionKey: null,
     });
   }, [pendingProjectRoot, pendingProjectRootSessionKey, selectedSession]);
 
@@ -289,91 +265,78 @@ export function NcpChatPage({ view }: ChatPageProps) {
     view,
     routeSessionKey,
     selectedSessionKey,
-    selectedAgentId,
-    setSelectedSessionKey: presenter.chatSessionListManager.setSelectedSessionKey,
-    setSelectedAgentId: presenter.chatSessionListManager.setSelectedAgentId,
+    setSelectedSessionKey:
+      presenter.chatSessionListManager.setSelectedSessionKey,
     selectedSessionKeyRef,
     resetStreamState: presenter.chatStreamActionsManager.resetStreamState,
-    resolveAgentIdFromSessionKey
   });
 
   useEffect(() => {
     presenter.chatUiManager.syncState({
-      pathname: location.pathname
+      pathname: location.pathname,
     });
     presenter.chatUiManager.bindActions({
       navigate,
-      confirm
+      confirm,
     });
   }, [confirm, location.pathname, navigate, presenter]);
 
-  const currentSessionDisplayName = selectedSession ? sessionDisplayName(selectedSession) : undefined;
-  const currentSessionTypeLabel =
-    sessionTypeOptions.find((option) => option.value === selectedSessionType)?.label ??
-    resolveSessionTypeLabel(selectedSessionType);
+  const availableAgents = (agentsQuery.data?.agents?.length ?? 0) > 0
+    ? (agentsQuery.data?.agents ?? [])
+    : [{ id: selectedSession?.agentId ?? selectedAgentId }];
+  const {
+    currentSessionDisplayName,
+    currentAgentId,
+    currentAgent,
+    parentSession,
+    currentSessionTypeLabel
+  } = useNcpChatDerivedState({
+    selectedSession,
+    selectedAgentId,
+    availableAgents,
+    parentSessionId,
+    sessionSummaries,
+    selectedSessionType,
+    sessionTypeOptions
+  });
 
   useEffect(() => {
-    presenter.chatInputManager.syncSnapshot({
-      isProviderStateResolved,
-      defaultSessionType,
-      canStopGeneration: canStopCurrentRun,
-      stopDisabledReason,
-      stopSupported: true,
-      stopReason: undefined,
-      sendError: lastSendError,
-      isSending,
-      modelOptions,
-      sessionTypeOptions,
-      selectedSessionType,
-      canEditSessionType,
-      sessionTypeUnavailable,
-      skillRecords,
-      isSkillsLoading: sessionSkillsQuery.isLoading
-    });
-    presenter.chatThreadManager.syncSnapshot({
-      isProviderStateResolved,
-      modelOptions,
-      sessionTypeUnavailable,
-      sessionTypeUnavailableMessage,
-      sessionTypeLabel: currentSessionTypeLabel,
-      sessionKey,
-      sessionDisplayName: currentSessionDisplayName,
-      sessionProjectRoot: effectiveSessionProjectRoot,
-      sessionProjectName: effectiveSessionProjectName,
-      canDeleteSession: Boolean(selectedSession),
-      threadRef,
-      isHistoryLoading: agent.isHydrating,
-      messages: agent.visibleMessages,
-      isSending,
-      isAwaitingAssistantOutput
-    });
-  }, [
-    agent.isHydrating,
-    canEditSessionType,
-    canStopCurrentRun,
-    currentSessionDisplayName,
-    currentSessionTypeLabel,
-    defaultSessionType,
-    sessionSkillsQuery.isLoading,
-    isAwaitingAssistantOutput,
+    if (!selectedSession?.agentId || selectedAgentId === selectedSession.agentId) {
+      return;
+    }
+    presenter.chatSessionListManager.setSelectedAgentId(selectedSession.agentId);
+  }, [presenter, selectedAgentId, selectedSession?.agentId]);
+
+  useNcpChatSnapshotSync({
+    presenter,
     isProviderStateResolved,
-    isSending,
+    defaultSessionType,
+    canStopCurrentRun,
+    stopDisabledReason,
     lastSendError,
+    isSending,
     modelOptions,
-    presenter,
-    effectiveSessionProjectName,
-    effectiveSessionProjectRoot,
-    selectedSession,
-    sessionKey,
-    selectedSessionType,
     sessionTypeOptions,
+    selectedSessionType,
+    canEditSessionType,
     sessionTypeUnavailable,
-    sessionTypeUnavailableMessage,
     skillRecords,
-    stopDisabledReason,
+    isSkillsLoading: sessionSkillsQuery.isLoading,
+    sessionTypeUnavailableMessage,
+    currentSessionTypeLabel,
+    sessionKey,
+    currentAgentId,
+    currentAgent,
+    availableAgents,
+    currentSessionDisplayName,
+    effectiveSessionProjectRoot,
+    effectiveSessionProjectName,
+    selectedSession,
     threadRef,
-    agent.visibleMessages
-  ]);
+    agent,
+    isAwaitingAssistantOutput,
+    parentSession
+  });
 
   return (
     <ChatPresenterProvider presenter={presenter}>

package/src/components/chat/ncp/README.md

@@ -0,0 +1,3 @@
+## 子树边界豁免
+
+- 原因：`chat/ncp/` 目录是 NCP 聊天运行时的装配子树，需要并列保留页面数据、派生状态、输入/线程 manager、session adapter 与测试文件。本次新增派生状态模块是为了拆短 `NcpChatPage.tsx`，属于职责下沉，而不是继续把复杂度堆回页面壳。

package/src/components/chat/ncp/ncp-chat-page-data.test.ts

@@ -48,10 +48,12 @@ describe('buildNcpSendMetadata', () => {
   it('includes the project root in the first-message metadata when present', () => {
     expect(
       buildNcpSendMetadata({
+        agentId: 'engineer',
         sessionType: 'codex',
         projectRoot: ' /tmp/project-alpha ',
       }),
     ).toMatchObject({
+      agent_id: 'engineer',
       session_type: 'codex',
       project_root: '/tmp/project-alpha',
     });

package/src/components/chat/ncp/ncp-chat-thread.manager.ts

@@ -1,11 +1,15 @@
 import { appQueryClient } from '@/app-query-client';
 import { deleteNcpSessionSummaryInQueryClient } from '@/api/ncp-session-query-cache';
 import { deleteNcpSession as deleteNcpSessionApi } from '@/api/ncp-session';
+import type { ChatToolActionViewModel } from '@nextclaw/agent-chat-ui';
 import type { ChatSessionListManager } from '@/components/chat/managers/chat-session-list.manager';
 import type { ChatStreamActionsManager } from '@/components/chat/managers/chat-stream-actions.manager';
 import type { ChatUiManager } from '@/components/chat/managers/chat-ui.manager';
 import { useChatSessionListStore } from '@/components/chat/stores/chat-session-list.store';
-import type { ChatThreadSnapshot } from '@/components/chat/stores/chat-thread.store';
+import type {
+  ChatChildSessionTab,
+  ChatThreadSnapshot,
+} from '@/components/chat/stores/chat-thread.store';
 import { useChatThreadStore } from '@/components/chat/stores/chat-thread.store';
 import { t } from '@/lib/i18n';
 
@@ -45,6 +49,107 @@ export class NcpChatThreadManager {
     this.uiManager.goToProviders();
   };
 
+  private upsertChildSessionTab = (tab: ChatChildSessionTab) => {
+    const { snapshot } = useChatThreadStore.getState();
+    const existingIndex = snapshot.childSessionTabs.findIndex(
+      (item) => item.sessionKey === tab.sessionKey,
+    );
+    const nextTabs =
+      existingIndex >= 0
+        ? snapshot.childSessionTabs.map((item, index) =>
+            index === existingIndex ? { ...item, ...tab } : item,
+          )
+        : [...snapshot.childSessionTabs, tab];
+    useChatThreadStore.getState().setSnapshot({
+      childSessionTabs: nextTabs,
+      activeChildSessionKey: tab.sessionKey,
+    });
+  };
+
+  openSessionFromToolAction = (action: ChatToolActionViewModel) => {
+    if (action.kind !== 'open-session') {
+      return;
+    }
+    if (action.sessionKind === 'child' && !this.isCompactViewport()) {
+      const parentSessionKey =
+        action.parentSessionId?.trim() ||
+        useChatSessionListStore.getState().snapshot.selectedSessionKey ||
+        null;
+      this.upsertChildSessionTab({
+        sessionKey: action.sessionId,
+        parentSessionKey,
+        label: action.label?.trim() || null,
+        agentId: action.agentId?.trim() || null,
+      });
+      return;
+    }
+    this.uiManager.goToSession(action.sessionId);
+  };
+
+  selectChildSessionDetail = (sessionKey: string) => {
+    const normalizedSessionKey = sessionKey.trim();
+    if (!normalizedSessionKey) {
+      return;
+    }
+    const { childSessionTabs } = useChatThreadStore.getState().snapshot;
+    if (!childSessionTabs.some((tab) => tab.sessionKey === normalizedSessionKey)) {
+      return;
+    }
+    useChatThreadStore.getState().setSnapshot({
+      activeChildSessionKey: normalizedSessionKey,
+    });
+  };
+
+  closeChildSessionDetail = () => {
+    const {
+      sessionKey,
+      childSessionTabs,
+      activeChildSessionKey,
+    } = useChatThreadStore.getState().snapshot;
+    if (!sessionKey) {
+      useChatThreadStore.getState().setSnapshot({
+        childSessionTabs: [],
+        activeChildSessionKey: null,
+      });
+      return;
+    }
+    const nextTabs = childSessionTabs.filter(
+      (tab) => tab.parentSessionKey !== sessionKey,
+    );
+    const nextActiveKey = nextTabs.some((tab) => tab.sessionKey === activeChildSessionKey)
+      ? activeChildSessionKey
+      : null;
+    useChatThreadStore.getState().setSnapshot({
+      childSessionTabs: nextTabs,
+      activeChildSessionKey: nextActiveKey,
+    });
+  };
+
+  goToParentSession = () => {
+    const {
+      parentSessionKey,
+      childSessionTabs,
+      activeChildSessionKey,
+    } = useChatThreadStore.getState().snapshot;
+    const activeChildParentSessionKey =
+      childSessionTabs.find((tab) => tab.sessionKey === activeChildSessionKey)
+        ?.parentSessionKey ?? null;
+    const resolvedParentSessionKey =
+      parentSessionKey ?? activeChildParentSessionKey;
+    if (!resolvedParentSessionKey) {
+      return;
+    }
+    this.closeChildSessionDetail();
+    this.uiManager.goToSession(resolvedParentSessionKey);
+  };
+
+  private isCompactViewport = (): boolean => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+      return false;
+    }
+    return window.matchMedia('(max-width: 767px)').matches;
+  };
+
   private deleteCurrentSession = async () => {
     const {
       snapshot: { selectedSessionKey }