feat(chat): live terminal card for client-hosted ACP terminals (#3861)

* feat(chat): live terminal card for client-hosted ACP terminals

New acp_terminal_output stream frame renders a terminal-style card:
mono command header, tail-following output pane, and a per-command Stop
button that calls POST /conversations/{id}/terminals/{terminalId}/kill —
killing just that command while the agent and turn continue. Cards are
keyed by terminal_id (all frames of a turn share one msg_id, so a
dedicated index stops two terminals collapsing into one card) and are
live-only: they are never persisted and vanish on reload. New i18n keys
conversation.terminal.* in all 13 locales.

* test(e2e): client-hosted terminal card and stop button

Two Playwright specs against codebuddy through the real UI: a delegated
command must render the live terminal card (mono command header + output
pane fed by acp_terminal_output frames), and the card's Stop button must
kill just that command — output stops mid-stream and the agent keeps
replying. Terminal card gains stable testids for both specs.

Note on the stop prompt: a bare long  is not usable — codebuddy
treats it as a timeout risk and reroutes it to its own background-task
tool, never touching terminal/*. A ticking loop goes through the
delegated terminal and stays killable mid-stream.

---------

Co-authored-by: zk <zk@users.noreply.local>

Author: kaizhou-lab

packages/desktop/src/common/adapter/ipcBridge.ts

@@ -264,6 +264,10 @@ export const conversation = {
     (p) => `/api/conversations/${p.conversation_id}/cancel`,
     (p) => ({ turn_id: p.turn_id })
   ),
+  killTerminal: httpPost<void, { conversation_id: string; terminal_id: string }>(
+    (p) => `/api/conversations/${p.conversation_id}/terminals/${encodeURIComponent(p.terminal_id)}/kill`,
+    () => undefined
+  ),
   activeCount: httpGet<{ count: number }>('/api/conversations/active-count'),
   sendMessage: httpPost<ISendMessageResult, ISendMessageParams>(
     (p) => `/api/conversations/${p.conversation_id}/messages`,

packages/desktop/src/common/chat/chatLib.ts

@@ -68,7 +68,8 @@ type TMessageType =
   | 'acp_tool_call'
   | 'plan'
   | 'thinking'
-  | 'available_commands';
+  | 'available_commands'
+  | 'acp_terminal_output';
 
 interface IMessage<T extends TMessageType, Content extends Record<string, any>> {
   /**
@@ -324,6 +325,19 @@ export type IMessagePermission = IMessage<'permission', IConfirmation>;
 
 export type IMessageAcpToolCall = IMessage<'acp_tool_call', ToolCallUpdate>;
 
+/** Live snapshot of a client-hosted terminal (ACP terminal/*). Stream-only —
+ * never persisted; the card disappears on conversation reload. */
+export interface AcpTerminalOutputContent {
+  terminal_id: string;
+  command: string;
+  /** Cumulative output (backend sends the full buffer each frame). */
+  output: string;
+  truncated: boolean;
+  exit_status?: { exit_code?: number | null; signaled?: boolean } | null;
+}
+
+export type IMessageAcpTerminalOutput = IMessage<'acp_terminal_output', AcpTerminalOutputContent>;
+
 export const mergeAcpToolCallContent = (
   existing: IMessageAcpToolCall['content'],
   incoming: IMessageAcpToolCall['content']
@@ -406,7 +420,8 @@ export type TMessage =
   | IMessageAcpToolCall
   | IMessagePlan
   | IMessageThinking
-  | IMessageAvailableCommands;
+  | IMessageAvailableCommands
+  | IMessageAcpTerminalOutput;
 
 // 统一所有需要用户交互的用户类型
 export interface IConfirmation<Option extends any = any> {
@@ -806,6 +821,21 @@ const transformMessageInner = (message: IResponseMessage): TMessage | undefined
         content: message.data as any,
       };
     }
+    case 'acp_terminal_output': {
+      const terminal = message.data as any;
+      return {
+        // Deterministic id per terminal: every frame of a turn shares one
+        // msg_id, so a uuid per frame would stack cards and the msg_id
+        // fallback merge would collapse two terminals into one.
+        id: `term:${message.msg_id}:${terminal?.terminal_id ?? ''}`,
+        type: 'acp_terminal_output',
+        msg_id: message.msg_id,
+        position: 'left',
+        conversation_id: message.conversation_id,
+        created_at,
+        content: terminal,
+      };
+    }
     case 'acp_tool_call': {
       return {
         id: uuid(),

packages/desktop/src/renderer/pages/conversation/Messages/MessageList.tsx

@@ -16,6 +16,7 @@ import { Down } from '@icon-park/react';
 import MessageAcpPermission from '@renderer/pages/conversation/Messages/acp/MessageAcpPermission';
 import MessageQuestion from './MessageQuestion';
 import MessagePermission from './components/MessagePermission';
+import MessageAcpTerminalOutput from '@renderer/pages/conversation/Messages/acp/MessageAcpTerminalOutput';
 import MessageAcpToolCall from '@renderer/pages/conversation/Messages/acp/MessageAcpToolCall';
 import classNames from 'classnames';
 import React, { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
@@ -293,6 +294,8 @@ const MessageItem: React.FC<{
           return <MessageQuestion message={message}></MessageQuestion>;
         case 'acp_tool_call':
           return <MessageAcpToolCall message={message}></MessageAcpToolCall>;
+        case 'acp_terminal_output':
+          return <MessageAcpTerminalOutput message={message}></MessageAcpTerminalOutput>;
         case 'plan':
           return <MessagePlan message={message}></MessagePlan>;
         case 'thinking':

packages/desktop/src/renderer/pages/conversation/Messages/acp/MessageAcpTerminalOutput.tsx

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * Copyright 2025 AionUi (aionui.com)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ipcBridge } from '@/common';
+import type { IMessageAcpTerminalOutput } from '@/common/chat/chatLib';
+import { Button, Card, Tag } from '@arco-design/web-react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+/**
+ * Live card for a client-hosted terminal (ACP terminal/*): the delegated
+ * command runs in OUR process tree, so output streams in real time and the
+ * stop button kills just this command — the agent observes the signal exit
+ * and the turn continues.
+ */
+const MessageAcpTerminalOutput: React.FC<{ message: IMessageAcpTerminalOutput }> = ({ message }) => {
+  const { t } = useTranslation();
+  const { content, conversation_id } = message;
+  const outputRef = useRef<HTMLPreElement>(null);
+  const [killing, setKilling] = useState(false);
+
+  const running = !content?.exit_status;
+
+  // Tail-follow the output while the command runs.
+  useEffect(() => {
+    const el = outputRef.current;
+    if (el && running) {
+      el.scrollTop = el.scrollHeight;
+    }
+  }, [content?.output, running]);
+
+  const handleStop = useCallback(async () => {
+    if (!conversation_id || !content?.terminal_id) return;
+    setKilling(true);
+    try {
+      await ipcBridge.conversation.killTerminal.invoke({
+        conversation_id,
+        terminal_id: content.terminal_id,
+      });
+    } catch (error) {
+      console.error('[MessageAcpTerminalOutput] kill failed:', error);
+      setKilling(false);
+    }
+  }, [conversation_id, content?.terminal_id]);
+
+  if (!content?.terminal_id) {
+    return null;
+  }
+
+  const exit = content.exit_status;
+  const statusTag = running ? (
+    <Tag color='arcoblue' size='small' data-testid='terminal-card-status'>
+      {t('conversation.terminal.running', { defaultValue: 'Running' })}
+    </Tag>
+  ) : exit?.signaled ? (
+    <Tag color='orange' size='small' data-testid='terminal-card-status'>
+      {t('conversation.terminal.stopped', { defaultValue: 'Stopped' })}
+    </Tag>
+  ) : (
+    <Tag color={exit?.exit_code === 0 ? 'green' : 'red'} size='small' data-testid='terminal-card-status'>
+      {t('conversation.terminal.exited', { defaultValue: 'Exit {{code}}', code: exit?.exit_code ?? '?' })}
+    </Tag>
+  );
+
+  return (
+    <Card className='w-full mb-2' size='small' bordered>
+      <div className='flex items-center gap-2 mb-2 min-w-0'>
+        <code className='text-13px font-mono text-t-primary truncate flex-1' data-testid='terminal-card-command'>
+          $ {content.command}
+        </code>
+        {statusTag}
+        {running && (
+          <Button size='mini' status='danger' loading={killing} onClick={handleStop} data-testid='terminal-card-stop'>
+            {t('conversation.terminal.stop', { defaultValue: 'Stop' })}
+          </Button>
+        )}
+      </div>
+      {(content.output || running) && (
+        <pre
+          ref={outputRef}
+          data-testid='terminal-card-output'
+          className='bg-1 p-2 rounded text-xs font-mono overflow-x-auto overflow-y-auto max-h-320px whitespace-pre-wrap m-0'
+        >
+          {content.truncated
+            ? `…${t('conversation.terminal.truncated', { defaultValue: '(earlier output truncated)' })}\n`
+            : ''}
+          {content.output || ''}
+        </pre>
+      )}
+    </Card>
+  );
+};
+
+export default MessageAcpTerminalOutput;

packages/desktop/src/renderer/pages/conversation/Messages/hooks.ts

@@ -57,6 +57,7 @@ interface MessageIndex {
   call_idIndex: Map<string, number>; // tool_call.call_id -> index
   tool_call_idIndex: Map<string, number>; // acp_tool_call.update.tool_call_id -> index
   permission_call_idIndex: Map<string, number>; // permission.content.call_id -> index
+  terminal_idIndex: Map<string, number>; // acp_terminal_output.content.terminal_id -> index
 }
 
 function getMessageIndexKey(message: TMessage): string | undefined {
@@ -88,6 +89,7 @@ export function buildMessageIndex(list: TMessage[]): MessageIndex {
   const call_idIndex = new Map<string, number>();
   const tool_call_idIndex = new Map<string, number>();
   const permission_call_idIndex = new Map<string, number>();
+  const terminal_idIndex = new Map<string, number>();
 
   for (let i = 0; i < list.length; i++) {
     const msg = list[i];
@@ -104,9 +106,12 @@ export function buildMessageIndex(list: TMessage[]): MessageIndex {
     if (msg.type === 'permission' && msg.content?.call_id) {
       permission_call_idIndex.set(msg.content.call_id, i);
     }
+    if (msg.type === 'acp_terminal_output' && msg.content?.terminal_id) {
+      terminal_idIndex.set(msg.content.terminal_id, i);
+    }
   }
 
-  return { msgIdIndex, call_idIndex, tool_call_idIndex, permission_call_idIndex };
+  return { msgIdIndex, call_idIndex, tool_call_idIndex, permission_call_idIndex, terminal_idIndex };
 }
 
 // 获取或构建索引（带缓存）
@@ -204,6 +209,24 @@ export function composeMessageWithIndex(
     return list.concat(message);
   }
 
+  // acp_terminal_output: one live card per terminal_id, replaced in place
+  // (every frame of a turn shares msg_id, so the generic msg_id arm would
+  // collapse two terminals of the same turn into one card).
+  if (message.type === 'acp_terminal_output' && message.content?.terminal_id) {
+    const existingIdx = index.terminal_idIndex.get(message.content.terminal_id);
+    if (existingIdx !== undefined && existingIdx < list.length) {
+      const existingMsg = list[existingIdx];
+      if (existingMsg.type === 'acp_terminal_output') {
+        const newList = list.slice();
+        newList[existingIdx] = { ...existingMsg, content: message.content };
+        return newList;
+      }
+    }
+    const newIdx = list.length;
+    index.terminal_idIndex.set(message.content.terminal_id, newIdx);
+    return list.concat(message);
+  }
+
   // acp_tool_call: use tool_call_idIndex for fast lookup
   if (message.type === 'acp_tool_call' && message.content?.update?.tool_call_id) {
     const existingIdx = index.tool_call_idIndex.get(message.content.update.tool_call_id);
@@ -413,6 +436,9 @@ export const useMergeLiveMessage = () => {
           if (msg.type === 'permission' && msg.content?.call_id) {
             index.permission_call_idIndex.set(msg.content.call_id, newIdx);
           }
+          if (msg.type === 'acp_terminal_output' && msg.content?.terminal_id) {
+            index.terminal_idIndex.set(msg.content.terminal_id, newIdx);
+          }
           newList = newList.concat(msg);
         } else {
           // 使用索引优化的消息合并

packages/desktop/src/renderer/pages/conversation/platforms/acp/useAcpMessage.ts

@@ -478,6 +478,12 @@ export const useAcpMessage = (
           }
           break;
         }
+        case 'acp_terminal_output':
+          // Live client-hosted terminal snapshot. Merge the card only — the
+          // frame can trail the turn's Finish (final exit snapshot), so it
+          // must not re-light turn state like the default arm does.
+          mergeLiveMessage(transformedMessage);
+          break;
         case 'acp_context_usage': {
           const usageData = message.data as {
             used: number;

packages/desktop/src/renderer/services/i18n/i18n-keys.d.ts

@@ -688,6 +688,11 @@ export type I18nKey =
   | 'conversation.skill_generator.type_skill'
   | 'conversation.skills.loaded'
   | 'conversation.skills.slashHint'
+  | 'conversation.terminal.exited'
+  | 'conversation.terminal.running'
+  | 'conversation.terminal.stop'
+  | 'conversation.terminal.stopped'
+  | 'conversation.terminal.truncated'
   | 'conversation.thinking.complete'
   | 'conversation.thinking.label'
   | 'conversation.welcome.clearWorkspace'

packages/desktop/src/renderer/services/i18n/locales/de-DE/conversation.json

@@ -631,5 +631,12 @@
       "empty": "Keine passenden Dateien",
       "limitReached": "Erste {{count}} werden angezeigt — eingrenzen"
     }
+  },
+  "terminal": {
+    "running": "Läuft",
+    "stopped": "Gestoppt",
+    "exited": "Exit {{code}}",
+    "stop": "Stopp",
+    "truncated": "(frühere Ausgabe gekürzt)"
   }
 }

packages/desktop/src/renderer/services/i18n/locales/en-US/conversation.json

@@ -631,5 +631,12 @@
       "empty": "No files match",
       "limitReached": "Showing first {{count}} — refine to narrow"
     }
+  },
+  "terminal": {
+    "running": "Running",
+    "stopped": "Stopped",
+    "exited": "Exit {{code}}",
+    "stop": "Stop",
+    "truncated": "(earlier output truncated)"
   }
 }

packages/desktop/src/renderer/services/i18n/locales/es-ES/conversation.json

@@ -631,5 +631,12 @@
       "empty": "Ningún archivo coincide",
       "limitReached": "Mostrando los primeros {{count}} — afina la búsqueda"
     }
+  },
+  "terminal": {
+    "running": "En ejecución",
+    "stopped": "Detenido",
+    "exited": "Salida {{code}}",
+    "stop": "Detener",
+    "truncated": "(salida anterior truncada)"
   }
 }