langchain_agentx_stream_ui

React 组件库：将 LangchainAgentEvent 流归并为可渲染的会话时间线。

快速接入

npm install langchain_agentx_stream_ui

import 'langchain_agentx_stream_ui/styles/default.css';
import { AgentSession, createAgentxSseSource } from 'langchain_agentx_stream_ui';

export function Chat({ url }: { url: string }) {
  const source = createAgentxSseSource({ url });
  return <AgentSession source={source} />;
}

V2-A API（Phase A）

• classifyEvent / resolveEventTier — 事件分级（main / collapsed / debug / state）
• AgentSession props：tierOverrides、debug
• ToolCallCard — summary → display → blocks；折叠区 details（input 流、progress、steps）
• reduceEvents(events, { tierOverrides, collectDebug })

V2-B API（Phase B · 回放）

• replayEvents(events, options?) / replayTree(tree, events, options?) — 纯函数离线回放
• createReplaySource(events, { delayMs?, tierOverrides? }) — 实现 Source 接口
• useReplayTree(events, options?) — React hook 只读树
• AgentSession prop initialEvents — 挂载时先 replay，再接 live Source 续流

import { AgentSession, createReplaySource, replayEvents } from 'langchain_agentx_stream_ui';

// 只读历史
<AgentSession source={createReplaySource(historyEvents)} />

// 历史 + 续流
<AgentSession source={liveSseSource} initialEvents={bufferedEvents} />

// 测试 / 调试
const tree = replayEvents(events);

示例见 examples/replay-from-events.tsx。

V2-B.x API（Phase B.x · SSE 续传 / M4）

• createAgentxSseSource 解析 SSE id: 行 → handler(event, { sseEventId })
• 网络断开后重连 URL 携带 last_event_id（buildResumeStreamUrl）
• createSessionStore 对重复 sseEventId 幂等跳过；tree.meta.lastEventId 记录游标

const source = createAgentxSseSource({
  url: '/api/stream',
  onLastEventId: (id) => localStorage.setItem('cursor', id),
});
// store 自动 dedupe 重叠帧

V2-C API（Phase C · 多会话）

• createMultiSessionStore(options?) — 多会话 zustand store（LRU 默认 10）
• MultiAgentSession — 每 session 独立 Source + initialEvents（EventBuffer 快照续流）
• useActiveSession() / useSessionIds() — 活跃 session 与 LRU 列表
• 单会话 AgentSession API 向后兼容不变

import { MultiAgentSession, createAgentxSseSource } from 'langchain_agentx_stream_ui';

<MultiAgentSession
  activeSessionId={tab}
  onActiveSessionChange={setTab}
  sessions={[
    { sessionId: 'a', source: sseA, initialEvents: bufferSnapshotA },
    { sessionId: 'b', source: sseB },
  ]}
/>

V2-D API（Phase D · 权限 UI）

• permission-request 事件 → PermissionNode（主舞台 PermissionCard）
• createInteractionBus({ onPermissionResolve }) — 薄层回写；库内不发起 HTTP
• AgentSession / MultiAgentSession prop interactionBus
• useInteractionBus() — 自定义节点内触发回写

import {
  AgentSession,
  createAgentxSseSource,
  createInteractionBus,
} from 'langchain_agentx_stream_ui';

const bus = createInteractionBus({
  onPermissionResolve: async ({ requestId, allow, message }) => {
    await fetch(`/task/${taskId}/permission`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        request_id: requestId,
        behavior: allow ? 'allow' : 'deny',
        message,
      }),
    });
  },
});

<AgentSession source={sseSource} interactionBus={bus} />;

V2-E API（Phase D · 虚拟滚动）

• VirtualTimeline — @tanstack/react-virtual 按主舞台 rootChildren 虚拟化
• AgentSession props：virtualized（默认 false）、virtualizeThreshold（默认 500）
• virtualized={false} 时与 MVP 全量 <Timeline /> 行为一致

<AgentSession source={source} virtualized virtualizeThreshold={500} />

可选子路径（减小主包依赖，需自行安装 @tanstack/react-virtual 若使用 virtual）：

import { VirtualTimeline } from 'langchain_agentx_stream_ui/virtual';
import { MultiAgentSession } from 'langchain_agentx_stream_ui/multi-session';
import { createDefaultToolRegistry } from 'langchain_agentx_stream_ui/tools';
import { MarkdownBlock } from 'langchain_agentx_stream_ui/tools/presentation';

V3-T API（Tool Display 子系统）

Per-tool Widget 套件，对齐 AgentX CLI widgets/tools/* 与 CC tools/*/UI.tsx。

决策树：NodeRegistry vs ToolDisplayRegistry

| 扩展点 | 替换范围 | 典型用途 | |--------|----------|----------| | NodeRegistry | 整卡（含 Shell 外布局） | 完全自定义 tool_call 节点 | | ToolDisplayRegistry | 仅 Body 组件 | 按工具名定制正文/标题语义 |

路由顺序（resolveToolBody）：registry 精确匹配 CC 工具名 → display.type → DefaultToolBody（无 alias 表）。

工具名 SSOT：frontend/src/view/tools/toolNames.ts（对齐 SDK registry_names.py）。门禁：tests/view/tools/toolNameGuard.test.ts（TN-006）。

已注册工具（default registry）

CC PascalCase 单键：Read / Write / Edit / Grep / Glob / Bash / Agent / Skill / WebSearch / WebFetch / AskUserQuestion

未注册或 legacy 名（如 read_file、batch_edit）回退 DefaultToolBody（summary + 折叠 JSON）。

接入示例

import {
  AgentSession,
  createDefaultToolRegistry,
  createAgentxSseSource,
} from 'langchain_agentx_stream_ui';

const tools = createDefaultToolRegistry();
// tools.register('my_tool', MyToolBody);

<AgentSession
  source={createAgentxSseSource({ url: '/api/stream' })}
  toolDisplayRegistry={tools}
  defaultBodyMode="preview"
/>;

• defaultBodyMode：preview（默认 3 行截断）或 full
• ToolCallShell：空标题工具使用 --bare 样式（无 chrome 头）
• MarkdownBlock：display.type=markdown 时用于 read 等文本类正文

T4.5 / T4.6（Grouped + 行内 Permission）

<AgentSession
  source={source}
  groupParallelTools
  permissionUiMode="inline"
  interactionBus={bus}
/>

| Prop | 默认 | 说明 | |------|------|------| | groupParallelTools | false | 连续同 toolName 的并行 tool_call 合并为 Grouped 行 | | permissionUiMode | standalone | inline 隐藏独立 PermissionCard，在 running 工具卡片内显示 Waiting… + Allow/Deny；both 双轨 |

后台 permission_mode=bypass 时通常不会出现 pending；逻辑预置供 raise 模式联调。

Grouped 与 virtualized 互斥：开启 groupParallelTools 时强制全量 Timeline（legacy；分组已由 projection GroupedToolUseAccumulator 承担）。

Renderable Projection（Phase 0–6）

Timeline 默认经 projectTimeline() 投影：collapsed_explore · grouped_tool_use · system_summary。

Phase 6 感官：shellProgressSuffix（bash ≥2s）、hint useMinDisplayTime(700ms)、git/MCP 摘要前缀。

Release notes：docs/release/frontend-renderable-projection_2026-06-07.md

import {
  AgentSession,
  projectTimeline,
  createProjectionContext,
  SystemSummaryAccumulator,
  formatShellProgressSuffix,
  useMinDisplayTime,
} from 'langchain_agentx_stream_ui';

<AgentSession
  source={source}
  displayMode="normal"       // normal | transcript | brief_only
  verbose={false}
  memoryDir="/path/to/memory"  // memory 工具折叠（I08–I12）
  workspaceRoot="/repo"
/>;

hook-finished / compact-* 写入 SessionTree.systemEvents，经 SystemSummaryAccumulator 渲染为 system_summary（I13）。

示例见 examples/custom-tool-display.tsx（对比 examples/custom-tool-node.tsx）。

测试

cd frontend && npm test
npm run typecheck

契约测试消费 backend/tests/fixtures/sse/*.events.json（SSOT）。