langchain_agentx_stream_ui 0.1.0

package/README.md

@@ -0,0 +1,236 @@
+# langchain_agentx_stream_ui
+
+React 组件库：将 `LangchainAgentEvent` 流归并为可渲染的会话时间线。
+
+## 快速接入
+
+```bash
+npm install langchain_agentx_stream_ui
+```
+
+```tsx
+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 续流
+
+```tsx
+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` 记录游标
+
+```tsx
+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 **向后兼容**不变
+
+```tsx
+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()` — 自定义节点内触发回写
+
+```tsx
+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 />` 行为一致
+
+```tsx
+<AgentSession source={source} virtualized virtualizeThreshold={500} />
+```
+
+可选子路径（减小主包依赖，需自行安装 `@tanstack/react-virtual` 若使用 virtual）：
+
+```tsx
+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）。
+
+### 接入示例
+
+```tsx
+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）
+
+```tsx
+<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`
+
+```tsx
+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`）。
+
+## 测试
+
+```bash
+cd frontend && npm test
+npm run typecheck
+```
+
+契约测试消费 `backend/tests/fixtures/sse/*.events.json`（SSOT）。

package/dist/AskUserQuestionToolBody-CyuNy_k5.d.ts

@@ -0,0 +1,33 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { b as ToolDisplayProps, T as ToolBodyComponent } from './types-aXj5TYSP.js';
+import { T as ToolDisplayRegistry } from './sessionViewOptions-DLSFRQwZ.js';
+
+declare function DefaultToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function resolveToolBody(toolName: string, display: unknown, registry: ToolDisplayRegistry): ToolBodyComponent;
+
+declare function formatToolTitle(toolName: string, input: unknown, display: unknown, summary?: string | null, meta?: unknown): string;
+
+declare function ReadToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function GrepToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function GlobToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function EditToolBody({ input, result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function WriteToolBody({ input, result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function BashToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function AgentToolBody({ result, bodyMode, onBodyModeChange, status, subagentProgress, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function WebSearchToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function WebFetchToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function SkillToolBody({ result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+declare function AskUserQuestionToolBody({ input, result, bodyMode, onBodyModeChange, }: ToolDisplayProps): react_jsx_runtime.JSX.Element;
+
+export { AgentToolBody as A, BashToolBody as B, DefaultToolBody as D, EditToolBody as E, GlobToolBody as G, ReadToolBody as R, SkillToolBody as S, WebFetchToolBody as W, AskUserQuestionToolBody as a, GrepToolBody as b, WebSearchToolBody as c, WriteToolBody as d, formatToolTitle as f, resolveToolBody as r };

package/dist/MarkdownBlock-3iEW0Ubm.d.ts

@@ -0,0 +1,100 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { a as ToolBodyMode } from './types-aXj5TYSP.js';
+
+declare const MAX_PREVIEW_LINES = 3;
+interface TruncatedContentProps {
+    text: string;
+    mode: ToolBodyMode;
+    maxLines?: number;
+    onExpand?: () => void;
+}
+declare function TruncatedContent({ text, mode, maxLines, onExpand, }: TruncatedContentProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * BodyBlockList.tsx — ⎿ 多块正文布局
+ *
+ * 职责：
+ *     多块平面文本，支持 normal / error / dim 变体。
+ *
+ * 链路位置：
+ *     T3 bash stdout/stderr 分块；DefaultToolBody 可复用。
+ *
+ * 当前裁剪范围：
+ *     块内不做 TruncatedContent（由调用方传入已截断文本）。
+ *
+ * 对齐参考：
+ *     CLI presentation/message_layout.py · CC MessageResponse.tsx ⎿ 前缀
+ */
+interface BodyBlock {
+    text: string;
+    variant?: 'normal' | 'error' | 'dim';
+}
+interface BodyBlockListProps {
+    blocks: BodyBlock[];
+}
+declare function BodyBlockList({ blocks }: BodyBlockListProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * paths.ts — 路径展示 helper
+ *
+ * 职责：
+ *     将绝对路径转为较短展示字符串（Web 无 cwd 时仅 normalize 分隔符）。
+ *
+ * 链路位置：
+ *     T1+ Read/Edit Widget title。
+ *
+ * 当前裁剪范围：
+ *     不做 relpath（浏览器无 process.cwd）；仅 slash 归一化。
+ *
+ * 对齐参考：
+ *     CLI widgets/tools/helpers.py display_path
+ */
+declare function displayPath(filePath: string): string;
+
+declare function formatPatternTitle(pattern: string, path?: string | null): string;
+declare function truncateLines(text: string, maxLines: number): {
+    text: string;
+    truncated: boolean;
+};
+declare function formatSearchResultBody(output: string, maxListLines?: number): string;
+
+interface DiffViewProps {
+    diff: string;
+    mode: ToolBodyMode;
+    maxPreviewLines?: number;
+    onExpand?: () => void;
+}
+declare function DiffView({ diff, mode, maxPreviewLines, onExpand, }: DiffViewProps): react_jsx_runtime.JSX.Element;
+
+type DiffLineKind = 'add' | 'remove' | 'context' | 'meta';
+interface ParsedDiffLine {
+    kind: DiffLineKind;
+    text: string;
+}
+declare function formatDiffFromStrings(oldText: string, newText: string): string;
+declare function parseDiffText(diff: string): ParsedDiffLine[];
+
+/**
+ * bashHelpers.ts — bash 命令与输出解析
+ *
+ * 对齐参考：CLI widgets/tools/helpers.py · bash/widget.py format_body_blocks
+ */
+
+declare function truncateCommand(command: string, maxChars?: number): string;
+declare function formatTimeoutFooter(timeoutMs: number | null | undefined): string | null;
+declare function buildBashBodyBlocks(display: unknown, summary: string, meta: unknown, mode: ToolBodyMode, isError: boolean): {
+    blocks: BodyBlock[];
+    truncated: boolean;
+    remainingLines: number;
+};
+
+interface MarkdownBlockProps {
+    text: string;
+    mode: ToolBodyMode;
+    maxLines?: number;
+    onExpand?: () => void;
+    className?: string;
+}
+declare function MarkdownBlock({ text, mode, maxLines, onExpand, className, }: MarkdownBlockProps): react_jsx_runtime.JSX.Element;
+
+export { type BodyBlock as B, DiffView as D, MAX_PREVIEW_LINES as M, TruncatedContent as T, BodyBlockList as a, MarkdownBlock as b, buildBashBodyBlocks as c, displayPath as d, formatPatternTitle as e, formatDiffFromStrings as f, formatSearchResultBody as g, formatTimeoutFooter as h, truncateLines as i, parseDiffText as p, truncateCommand as t };