@brainpilot/web 0.0.9 → 0.0.11

package/src/contexts/messageGroups.ts

@@ -2,12 +2,17 @@ import { ChatMessage } from "../contracts/backend";
 
 /**
  * A unit of rendering in the chat stream. Either a single standalone message
- * (user prompt, assistant text, error, hook note) or an "activity" group that
- * folds adjacent reasoning and tool calls/results into one collapsible block.
+ * (user prompt, assistant text, error, hook note), an "activity" group that
+ * folds adjacent reasoning and tool calls/results into one collapsible block,
+ * or (#219) an "expertGroup" that folds a run of non-PI (specialist) agent
+ * render items behind one more level of disclosure so the PI narrative reads
+ * cleanly by default. An expertGroup nests already-built single/activity items
+ * so the reasoning/tool folds inside it are preserved when expanded.
  */
 export type RenderItem =
   | { type: "single"; message: ChatMessage }
-  | { type: "activity"; id: string; steps: ChatMessage[]; streaming: boolean };
+  | { type: "activity"; id: string; steps: ChatMessage[]; streaming: boolean }
+  | { type: "expertGroup"; id: string; agents: string[]; items: RenderItem[]; streaming: boolean };
 
 /**
  * #134 — tool visibility model. Internal tools are part of the agent's plumbing
@@ -101,6 +106,7 @@ function isStandalone(message: ChatMessage): boolean {
 export function buildRenderItems(
   messages: ChatMessage[],
   runningAgents?: ReadonlySet<string>,
+  groupExpert = false,
 ): RenderItem[] {
   const items: RenderItem[] = [];
   // #134 — internal tools (trace bookkeeping) are hidden from the chat UI.
@@ -129,5 +135,105 @@ export function buildRenderItems(
     }
   }
   flush();
-  return items;
+  // #219 — second pass: fold consecutive specialist (non-PI) items into
+  // collapsible expert groups. Off by default (demo replay / legacy callers).
+  return groupExpert ? groupExpertItems(items, runningAgents) : items;
+}
+
+/* -------------------------------------------------------------------------- *
+ * #219 — expert-agent activity grouping.
+ * -------------------------------------------------------------------------- */
+
+/** The principal (PI) agent name; unattributed items default to it. */
+const PRINCIPAL = "principal";
+
+/**
+ * Important events stay visible even when they come from a specialist agent —
+ * they must never be buried inside a collapsed group (issue #219 UX goal:
+ * "avoid hiding important failures, blockers, or user-action-required events").
+ * Errors, approval/user-input requests, and warning+ system messages / hooks
+ * escape grouping and render standalone.
+ */
+function isImportantEvent(message: ChatMessage): boolean {
+  if (message.kind === "error" || message.kind === "ask_user") return true;
+  if (message.kind === "system_message") {
+    const level = message.systemMessage?.level;
+    return level === "warning" || level === "error" || level === "fatal";
+  }
+  if (message.kind === "hook") {
+    return message.hookLevel === "warning" || message.hookLevel === "error";
+  }
+  return false;
+}
+
+/** Owning agent of a render item: the message's agent, or the activity's first step. */
+function itemAgent(item: RenderItem): string {
+  if (item.type === "single") return item.message.agent ?? PRINCIPAL;
+  if (item.type === "activity") return item.steps[0]?.agent ?? PRINCIPAL;
+  return PRINCIPAL;
+}
+
+/**
+ * A render item is a foldable specialist item when it belongs to a non-PI agent
+ * AND (for singles) is not an important event that must stay surfaced. User
+ * prompts and PI/unattributed items always break the run.
+ */
+function isFoldableExpertItem(item: RenderItem): boolean {
+  if (itemAgent(item) === PRINCIPAL) return false;
+  if (item.type === "single") {
+    if (item.message.role === "user") return false;
+    if (isImportantEvent(item.message)) return false;
+  }
+  return true;
+}
+
+function itemStreaming(item: RenderItem, runningAgents?: ReadonlySet<string>): boolean {
+  if (item.type === "activity") return item.streaming;
+  if (item.type === "single") {
+    return !!item.message.streaming || (runningAgents?.has(itemAgent(item)) ?? false);
+  }
+  return false;
+}
+
+/** Fold consecutive foldable specialist items into one expertGroup each. */
+function groupExpertItems(items: RenderItem[], runningAgents?: ReadonlySet<string>): RenderItem[] {
+  const out: RenderItem[] = [];
+  let run: RenderItem[] = [];
+  const flushRun = () => {
+    if (run.length === 0) return;
+    // A lone expert `activity` item is already collapsed on its own — wrapping
+    // it in a second disclosure level just makes the user click twice. Leave it.
+    // A lone expert `single` (standalone text) still gets grouped so specialist
+    // chatter is collapsed by default (issue #219 acceptance criteria).
+    if (run.length === 1 && run[0].type === "activity") {
+      out.push(run[0]);
+      run = [];
+      return;
+    }
+    const agents = Array.from(new Set(run.map(itemAgent)));
+    out.push({
+      type: "expertGroup",
+      id: `expert-${idOf(run[0])}`,
+      agents,
+      items: run,
+      streaming: run.some((it) => itemStreaming(it, runningAgents)),
+    });
+    run = [];
+  };
+  for (const item of items) {
+    if (isFoldableExpertItem(item)) {
+      run.push(item);
+    } else {
+      flushRun();
+      out.push(item);
+    }
+  }
+  flushRun();
+  return out;
+}
+
+/** Stable id for a render item (drives <details> DOM reuse across re-renders). */
+function idOf(item: RenderItem): string {
+  if (item.type === "single") return item.message.id;
+  return item.id;
 }

package/src/contexts/messageReducer.ts

@@ -338,7 +338,17 @@ export function reduceMessagesForEvent(existing: ChatMessage[], event: WebSocket
 
     // 修正6 — system_message: 4-level styled bubble in the conversation stream.
     case "system_message": {
-      return [...existing, systemMessageToChatMessage(event)];
+      const msg = systemMessageToChatMessage(event);
+      // #167: coalesce by stable id — a repeated system_message carrying an id
+      // that already exists (e.g. an agent's retry warning ticking n/N) updates
+      // the existing bubble in place instead of stacking a new one. Messages
+      // without a stable id (random-id path) always append, as before.
+      const e = event as Record<string, unknown>;
+      const hasStableId = typeof (e.id ?? e.messageId) === "string";
+      if (hasStableId && existing.some((m) => m.id === msg.id)) {
+        return existing.map((m) => (m.id === msg.id ? msg : m));
+      }
+      return [...existing, msg];
     }
 
     // 修正6 — user_input_request (ask_user): interactive card. Keyed by

package/src/i18n/messages/chat.ts

@@ -18,11 +18,18 @@ export default defineMessages(
     "chat.aria.messages": "对话消息",
     "chat.messageCount": "{count} 条消息",
     "chat.aria.expandThinking": "展开思考过程",
+    "chat.expertGroup.summary": "{agent} 的活动 · {count} 项",
+    "chat.expertGroup.summaryMulti": "{n} 位专家 Agent · {count} 项活动",
+    "chat.expertGroup.expandAll": "展开全部活动",
+    "chat.expertGroup.collapseAll": "收起专家活动",
+    "chat.aria.expandExpert": "展开专家 Agent 活动",
     "chat.agentThinking": "智能体思考中",
     "chat.agentWorking": "{name} 正在工作",
     "chat.agentsWorking": "{names} 正在工作",
     "chat.aria.stop": "停止生成",
     "chat.stop": "停止",
+    "chat.runningScripts.count": "{count} 个脚本正在运行",
+    "chat.runningScripts.pending": "参数传输中…",
     "chat.aria.newPrompt": "新的研究提问",
     "chat.srAsk": "提出一个研究问题",
     "chat.placeholder": "向 MAS 提问。输入 @ 使用插件或提及文件",
@@ -81,11 +88,18 @@ export default defineMessages(
     "chat.aria.messages": "Conversation messages",
     "chat.messageCount": "{count} messages",
     "chat.aria.expandThinking": "Expand thinking process",
+    "chat.expertGroup.summary": "{agent} activity · {count} items",
+    "chat.expertGroup.summaryMulti": "{n} specialist agents · {count} activity items",
+    "chat.expertGroup.expandAll": "Expand all activity",
+    "chat.expertGroup.collapseAll": "Collapse specialist activity",
+    "chat.aria.expandExpert": "Expand specialist agent activity",
     "chat.agentThinking": "Agent is thinking",
     "chat.agentWorking": "{name} is working",
     "chat.agentsWorking": "{names} are working",
     "chat.aria.stop": "Stop generating",
     "chat.stop": "stop",
+    "chat.runningScripts.count": "{count} script(s) running",
+    "chat.runningScripts.pending": "receiving args…",
     "chat.aria.newPrompt": "New research prompt",
     "chat.srAsk": "Ask a research question",
     "chat.placeholder": "Ask MAS. Type @ to use plugins or mention files",

package/src/i18n/messages/sandbox.ts

@@ -45,6 +45,8 @@ export default defineMessages(
     "sandbox.logs.loading": "正在加载日志…",
     "sandbox.logs.empty": "尚未加载沙盒日志。",
     "sandbox.logs.failed": "加载沙盒详情失败。",
+    // details
+    "sandbox.details.more": "更多详情",
     // actions
     "sandbox.action.rebuild": "重建",
     "sandbox.action.refresh": "刷新",
@@ -100,6 +102,7 @@ export default defineMessages(
     "sandbox.logs.loading": "Loading logs...",
     "sandbox.logs.empty": "No sandbox logs loaded.",
     "sandbox.logs.failed": "Failed to load sandbox details.",
+    "sandbox.details.more": "More details",
     "sandbox.action.rebuild": "Rebuild",
     "sandbox.action.refresh": "Refresh",
     "sandbox.action.logs": "Logs",

package/src/i18n/messages/settings.ts

@@ -12,7 +12,42 @@ export default defineMessages(
     "settings.tab.account": "账户",
     "settings.tab.providers": "服务商",
     "settings.tab.mcp": "MCP",
+    "settings.tab.knowledgeBase": "知识库",
     "settings.tab.preferences": "偏好",
+    // knowledge base
+    "settings.kb.title": "本地知识库",
+    "settings.kb.desc": "将 PDF 放入 KnowledgeBase/source/pdf/，然后构建本地 RAG 索引。嵌入模型在本机运行；仅 OCR 与元数据抽取阶段需要联网。",
+    "settings.kb.ocrKey": "SiliconFlow OCR API Key",
+    "settings.kb.metaKey": "元数据抽取 API Key",
+    "settings.kb.metaBaseUrl": "元数据抽取 Base URL",
+    "settings.kb.metaModel": "元数据抽取模型",
+    "settings.kb.reuseAgentKey": "复用 agent 当前的 LLM key 进行元数据抽取",
+    "settings.kb.useHfMirror": "使用 HuggingFace 镜像下载模型（推荐国内用户开启）",
+    "settings.kb.useHfMirrorHint": "首次构建将自动下载 bge-m3 + bge-reranker-v2-m3 模型权重（约 2.5 GB）。国内用户开启此选项可切换到 hf-mirror.com 显著提升下载速度。",
+    "settings.kb.stages": "要运行的阶段",
+    "settings.kb.start": "构建知识库",
+    "settings.kb.cancel": "取消构建",
+    "settings.kb.progress": "阶段进度",
+    "settings.kb.log": "实时日志",
+    "settings.kb.logEmpty": "尚无构建事件 — 点击「构建知识库」开始。",
+    "settings.kb.error.missingOcrKey": "缺少 SiliconFlow OCR API Key",
+    "settings.kb.error.missingMetaKey": "缺少元数据抽取 API Key（或勾选「复用 agent LLM key」）",
+    "settings.kb.env.title": "Python 运行环境",
+    "settings.kb.env.venvMissing": "尚未为 KnowledgeBase 创建 Python 虚拟环境。点下面按钮一次性配置 Python 环境 + 下载模型：",
+    "settings.kb.env.setupButton": "一键配置 Python 环境",
+    "settings.kb.env.setupHint": "在 KnowledgeBase/.venv 里创建 venv 并安装 requirements.txt 中的所有依赖（约 2-5 分钟，需联网下载 PyTorch / FlagEmbedding）",
+    "settings.kb.env.setupFullButton": "一键配置环境 + 下载模型",
+    "settings.kb.env.setupFullHint": "同时执行：① 创建 .venv 并安装 Python 依赖（2-5 分钟）② 下载 bge-m3 + bge-reranker 模型权重（约 2.5 GB，5-30 分钟）。两步进度会分别显示。",
+    "settings.kb.env.reinstallButton": "重建虚拟环境",
+    "settings.kb.env.reinstallHint": "删除现有 .venv 并从头重装所有依赖",
+    "settings.kb.env.cliFallback": "或者也可以在终端手动执行",
+    "settings.kb.env.venvHint": "venv 创建后无需任何额外环境变量配置 —— 构建按钮会自动发现它。如果你想用别的解释器，把绝对路径写到 BP_KB_PYTHON 环境变量里再启动 BrainPilot。",
+    "settings.kb.env.needSetupFirst": "请先点击「一键配置环境 + 下载模型」",
+    "settings.kb.env.busy": "Python 环境配置正在进行中…",
+    "settings.kb.env.venvProgressLabel": "① Python 虚拟环境",
+    "settings.kb.env.modelProgressLabel": "② 嵌入 / 重排序模型",
+    "settings.kb.ocrKeySaved": "已保存",
+    "settings.kb.ocrKeyChange": "更改",
     // account
     "settings.account.title": "账户",
     "settings.account.username": "用户名",
@@ -38,6 +73,8 @@ export default defineMessages(
     "settings.providers.activeSwitched": "已切换活动服务商为 “{name}”。新会话将使用该服务商。",
     "settings.providers.saveFailed": "保存服务商失败",
     "settings.providers.modelRequired": "至少需要配置一个模型",
+    "settings.providers.empty": "还没有服务商",
+    "settings.providers.emptyHint": "添加一个服务商，配置 API 接入与可用模型后即可开始新会话。",
     // mcp
     "settings.mcp.title": "MCP 服务器",
     "settings.mcp.desc": "MCP 服务器配置定义了智能体会话可用的外部工具。",
@@ -47,15 +84,23 @@ export default defineMessages(
     "settings.mcp.updated": "MCP 服务器已更新",
     "settings.mcp.added": "MCP 服务器已添加",
     "settings.mcp.saveFailed": "保存 MCP 服务器失败",
+    "settings.mcp.empty": "还没有 MCP 服务器",
+    "settings.mcp.emptyHint": "添加一个 MCP 服务器，把外部工具接入你的智能体会话。",
     // preferences
     "settings.prefs.title": "偏好设置",
+    "settings.prefs.groupAppearance": "外观",
+    "settings.prefs.groupBehavior": "行为",
     "settings.prefs.theme": "主题",
+    "settings.prefs.themeDesc": "选择浅色、深色，或跟随系统设置。",
     "settings.prefs.themeLight": "浅色",
     "settings.prefs.themeDark": "深色",
     "settings.prefs.themeSystem": "跟随系统",
     "settings.prefs.language": "语言",
+    "settings.prefs.languageDesc": "界面显示语言。",
     "settings.prefs.confirmDangerous": "危险操作前确认",
+    "settings.prefs.confirmDangerousDesc": "执行删除、重建等不可撤销操作前先弹窗确认。",
     "settings.prefs.notifyDone": "智能体任务完成时通知",
+    "settings.prefs.notifyDoneDesc": "智能体完成任务后发送桌面通知。",
     // provider form
     "settings.providerForm.editAria": "编辑服务商",
     "settings.providerForm.addAria": "添加服务商",
@@ -76,6 +121,8 @@ export default defineMessages(
     "settings.providerForm.models": "模型",
     "settings.providerForm.addModel": "添加模型",
     "settings.providerForm.removeModel": "移除模型",
+    "settings.providerForm.modelsHint":
+      "示例模型仅作占位，保存前请改成你的网关支持的模型，否则发消息时才会报模型不可用。",
     "settings.providerForm.useColor": "使用颜色 {color}",
     "settings.providerForm.color": "颜色",
     "settings.providerForm.cancel": "取消",
@@ -107,7 +154,41 @@ export default defineMessages(
     "settings.tab.account": "Account",
     "settings.tab.providers": "Providers",
     "settings.tab.mcp": "MCP",
+    "settings.tab.knowledgeBase": "Knowledge Base",
     "settings.tab.preferences": "Preferences",
+    "settings.kb.title": "Local Knowledge Base",
+    "settings.kb.desc": "Drop PDFs into KnowledgeBase/source/pdf/, then build a local RAG index. Embedding models run on your machine; only the OCR and metadata-extraction stages call out.",
+    "settings.kb.ocrKey": "SiliconFlow OCR API key",
+    "settings.kb.metaKey": "Metadata-extract API key",
+    "settings.kb.metaBaseUrl": "Metadata-extract base URL",
+    "settings.kb.metaModel": "Metadata-extract model",
+    "settings.kb.reuseAgentKey": "Reuse the agent's active LLM key for metadata extraction",
+    "settings.kb.useHfMirror": "Use HuggingFace mirror for model download (recommended for users in China)",
+    "settings.kb.useHfMirrorHint": "First build auto-downloads bge-m3 + bge-reranker-v2-m3 weights (~2.5 GB). Users in China can enable this to switch to hf-mirror.com for much faster downloads.",
+    "settings.kb.stages": "Stages to run",
+    "settings.kb.start": "Build Knowledge Base",
+    "settings.kb.cancel": "Cancel build",
+    "settings.kb.progress": "Stage progress",
+    "settings.kb.log": "Live log",
+    "settings.kb.logEmpty": "No build events yet — press \"Build Knowledge Base\" to start.",
+    "settings.kb.error.missingOcrKey": "SiliconFlow OCR API key required",
+    "settings.kb.error.missingMetaKey": "Metadata-extract API key required (or check \"reuse agent LLM key\")",
+    "settings.kb.env.title": "Python environment",
+    "settings.kb.env.venvMissing": "No Python venv set up for KnowledgeBase yet. Click below to set up the Python env and download models in one go:",
+    "settings.kb.env.setupButton": "Set up Python environment",
+    "settings.kb.env.setupHint": "Creates KnowledgeBase/.venv and installs everything in requirements.txt (2-5 min; downloads PyTorch + FlagEmbedding)",
+    "settings.kb.env.setupFullButton": "Set up environment + download models",
+    "settings.kb.env.setupFullHint": "Runs in sequence: ① create .venv and install Python dependencies (2-5 min) ② download bge-m3 + bge-reranker weights (~2.5 GB, 5-30 min). Progress for each step is shown separately.",
+    "settings.kb.env.reinstallButton": "Reinstall venv",
+    "settings.kb.env.reinstallHint": "Remove the existing .venv and reinstall every dependency from scratch",
+    "settings.kb.env.cliFallback": "Or run this in a terminal yourself",
+    "settings.kb.env.venvHint": "Once the venv exists no env vars are needed — the build button auto-detects it. To use a different interpreter, set BP_KB_PYTHON to its absolute path before launching BrainPilot.",
+    "settings.kb.env.needSetupFirst": "Click \"Set up environment + download models\" first",
+    "settings.kb.env.venvProgressLabel": "① Python virtual environment",
+    "settings.kb.env.modelProgressLabel": "② Embedding + reranker models",
+    "settings.kb.ocrKeySaved": "Saved",
+    "settings.kb.ocrKeyChange": "Change",
+    "settings.kb.env.busy": "Python environment setup is currently running…",
     "settings.account.title": "Account",
     "settings.account.username": "Username",
     "settings.account.userId": "User ID",
@@ -131,6 +212,8 @@ export default defineMessages(
     "settings.providers.activeSwitched": "Active provider switched to \"{name}\". New sessions will use this provider.",
     "settings.providers.saveFailed": "Failed to save provider",
     "settings.providers.modelRequired": "At least one model is required",
+    "settings.providers.empty": "No providers yet",
+    "settings.providers.emptyHint": "Add a provider with its API connection and models to start new sessions.",
     "settings.mcp.title": "MCP Servers",
     "settings.mcp.desc": "MCP server profiles define external tools available to agent sessions.",
     "settings.mcp.addServer": "Add Server",
@@ -139,14 +222,22 @@ export default defineMessages(
     "settings.mcp.updated": "MCP server updated",
     "settings.mcp.added": "MCP server added",
     "settings.mcp.saveFailed": "Failed to save MCP server",
+    "settings.mcp.empty": "No MCP servers yet",
+    "settings.mcp.emptyHint": "Add an MCP server to connect external tools to your agent sessions.",
     "settings.prefs.title": "Preferences",
+    "settings.prefs.groupAppearance": "Appearance",
+    "settings.prefs.groupBehavior": "Behavior",
     "settings.prefs.theme": "Theme",
+    "settings.prefs.themeDesc": "Choose light, dark, or follow your system setting.",
     "settings.prefs.themeLight": "Light",
     "settings.prefs.themeDark": "Dark",
     "settings.prefs.themeSystem": "System",
     "settings.prefs.language": "Language",
+    "settings.prefs.languageDesc": "Display language for the interface.",
     "settings.prefs.confirmDangerous": "Confirm dangerous actions",
+    "settings.prefs.confirmDangerousDesc": "Ask before irreversible actions like deleting or rebuilding.",
     "settings.prefs.notifyDone": "Notify when agent work completes",
+    "settings.prefs.notifyDoneDesc": "Send a desktop notification when an agent finishes its task.",
     "settings.providerForm.editAria": "Edit provider",
     "settings.providerForm.addAria": "Add provider",
     "settings.providerForm.eyebrow": "Provider",
@@ -166,6 +257,8 @@ export default defineMessages(
     "settings.providerForm.models": "Models",
     "settings.providerForm.addModel": "Add model",
     "settings.providerForm.removeModel": "Remove model",
+    "settings.providerForm.modelsHint":
+      "The example model is only a placeholder — replace it with one your gateway supports before saving, or the model will be rejected when you send a message.",
     "settings.providerForm.useColor": "Use color {color}",
     "settings.providerForm.color": "Color",
     "settings.providerForm.cancel": "Cancel",

package/src/i18n/messages/trace.ts

@@ -4,7 +4,6 @@ export default defineMessages(
   {
     // AgentsPanel
     "trace.agents.eyebrow": "实时 Agent 网络",
-    "trace.agents.title": "Agents",
     "trace.agents.emptyNoSession": "创建或选择会话后，这里会显示参与当前任务的 Agent 与它们之间的消息流。",
     "trace.agents.emptyNoEvents": "当前会话还没有 Agent 状态事件。",
     // TracePanel
@@ -70,7 +69,6 @@ export default defineMessages(
     },
     {
     "trace.agents.eyebrow": "Live agent network",
-    "trace.agents.title": "Agents",
     "trace.agents.emptyNoSession": "Once you create or select a session, the agents involved in the current task and the message flow between them will appear here.",
     "trace.agents.emptyNoEvents": "No agent status events in this session yet.",
     "trace.eyebrow": "Reasoning trace",