@limecloud/agent-runtime-ui

@limecloud/agent-runtime-ui 是 Lime Cloud 系列应用共享的 Agent Runtime React UI primitives。它面向标准 AgentUiProjectionState，提供消息部件、过程时间线、执行图、运行事实栏、action / evidence / artifact 卡片等组件。

这个包是 UI 渲染层，不直接调用 JSON-RPC，不依赖 Electron，不绑定任何宿主应用的业务 store。宿主应用负责后端交互、session 持久化、业务对象和页面布局。

默认 label 只作为英文 fallback。宿主应用必须通过 labels / formatter props 注入自己的 aria、标题、按钮和状态文案，并负责 Lime current 五语言资源覆盖。

Installation

npm install @limecloud/agent-ui-contracts @limecloud/agent-runtime-ui @limecloud/agent-runtime-projection

React 是 peer dependency：

{
  "react": ">=18 <20",
  "react-dom": ">=18 <20"
}

Boundary

这个包负责：

• 渲染 AgentUiProjectionState 标准 UI surface。
• 渲染 UIMessageParts 消息部件。
• 渲染 ProcessTimeline 过程时间线。
• 渲染 ExecutionGraph 执行图。
• 渲染 state.subagents 标准子代理模型。
• 渲染 Agent 消息时间线。
• 渲染运行事实摘要。
• 渲染 action、evidence、artifact、tool 等 runtime facts。
• 渲染 ArtifactRef / EvidenceRef 轻量引用列表，并把打开意图交还宿主应用。
• 渲染标准多 action controls，并通过 data-action-decision 暴露稳定 DOM contract。
• 通过 callback 把用户处理 action 的意图交还给宿主应用。

这个包不负责：

• 订阅 JSON-RPC 或调用 App Server。
• 管理 session store。
• 打开业务页面或路由。
• 提供全局 CSS reset、主题系统或业务文案体系。
• 渲染 Prompt 草稿、知识库、素材、审核任务等宿主业务壳。

Usage

最推荐的入口是 AgentUiProjectionView。宿主先用 projection 包得到 AgentUiProjectionState，再把 state 传给 UI 包：

import { AgentUiProjectionView } from "@limecloud/agent-runtime-ui";
import { projectAgentUiState } from "@limecloud/agent-runtime-projection";

const state = projectAgentUiState({
  executionEvents: session.executionEvents,
  sourceCount: session.sourceSnapshots.length,
});

export function AgentPanel() {
  return (
    <AgentUiProjectionView
      state={state}
      onResolveAction={(event, action) => {
        // 宿主应用决定打开哪个业务模块或发送哪个 action response。
        console.log(event.id, action.decision);
      }}
      labels={{
        messagePartsAriaLabel: t("agent.messages"),
        processTimelineAriaLabel: t("agent.timeline"),
        actionRequiredAriaLabel: t("agent.actionRequired"),
        actionButtonLabel: (action) => t(`agent.action.${action.decision}`),
      }}
    />
  );
}

如果宿主已经通过 App Server facts replay 得到 state，也可以直接渲染：

import { AgentUiProjectionView } from "@limecloud/agent-runtime-ui";
import { replayAppServerFacts } from "@limecloud/agent-runtime-projection";

const replay = replayAppServerFacts({
  readModel,
  events,
  evidenceExport,
});

<AgentUiProjectionView
  state={replay.state}
  onResolveAction={(event, action) => {
    actionResponder.respond(event, action);
  }}
/>;

onResolveAction 只表达用户意图。真正的后端调用应回到宿主的 runtime client，例如 AgentRuntimeClient.respondAction(...)。

React Surface Model

这个包采用 controlled component 模式：宿主传入 AgentUiProjectionState 和 command callbacks，组件只负责渲染、稳定 DOM contract 和用户意图回调。

| Surface | Standard input | Owner of business behavior | | --- | --- | --- | | Message parts | state.messages | 宿主提供消息列表区域布局和本地化 label。 | | Process timeline | state.timeline | projection 负责排序和 entry kind；宿主负责样式。 | | Execution graph | state.graph | projection 负责 parent/child edge；宿主负责布局密度。 | | Action required | state.actions | 宿主通过 runtime client 提交 action response。 | | Tool group | state.tools | projection 负责 tool lifecycle 解释。 | | Subagents | state.subagents | projection 负责子代理线程、委派调用、活动摘要和隔离摘要。 | | Artifact refs | state.artifacts | 宿主负责打开 artifact workspace 或详情页。 | | Evidence refs | state.evidence | 宿主负责打开 evidence pack、review 或 replay。 | | Runtime summary | state.readModel | projection/read model 负责计数；宿主负责显示文案。 |

当前包不提供 hooks。useAgentRuntimeClient、useAgentRuntimeFacts、useAgentUiProjector 等 hook 应留在产品应用或后续单独 adapter 包里；共享 React primitives 不订阅 runtime、不持有 session store、不读取 App Server。

Components

| 组件 | 输入 | 用途 | | --- | --- | --- | | AgentUiProjectionView | AgentUiProjectionState | 标准组合入口，渲染消息、过程、事实栏、action 和 graph。 | | UIMessagePartsView | UIMessageParts | 渲染标准消息部件。 | | ProcessTimelineView | ProcessTimeline | 渲染线性执行过程。 | | ExecutionGraphView | ExecutionGraph | 渲染 run / task / tool / subagent 结构。 | | SubagentsView | AgentUiProjectionState | 从 state.subagents 渲染子代理标准面。 | | SubagentThreadList | AgentUiSubagentThreadView[] | 渲染子代理线程、身份、状态、refs 摘要。 | | SubagentDelegationList | AgentUiSubagentDelegationView[] | 渲染 spawn / handoff / wait / interrupt 等委派调用。 | | SubagentActivityList | AgentUiSubagentActivityView[] | 渲染 started / handoff / review / completed / failed 等活动摘要。 | | ArtifactRefList | AgentUiArtifactRefView[] | 渲染 artifact refs，不读取大 payload。 | | EvidenceRefList | AgentUiEvidenceRefView[] | 渲染 evidence refs，不读取证据内容。 | | AgentUiRefList | AgentUiRefView[] | refs 通用 primitive。 | | RuntimeFactsPanel | AgentRuntimeReadModel | 兼容事实栏入口。 | | RuntimeFactsSummary | AgentRuntimeReadModel | 渲染 source / action / artifact / evidence 计数。 | | RuntimeEventList | AgentRuntimeEventProjection[] | 渲染一般 runtime event 列表。 | | ToolGroup | tool events | 渲染工具调用分组。 | | ActionRequiredList | action events | 渲染待处理 action。 | | RuntimeFactCard | runtime event | 渲染单个 runtime fact。 | | ActionCard / EvidenceCard / ArtifactCard | runtime event | 语义化 card alias，方便宿主样式分层。 | | AgentTimeline | host message list | 兼容传统消息列表，不是新 projection 默认入口。 |

Labels And I18n

默认 label 只是 fallback。Lime 产品应用必须传入自己的 i18n label 和 formatter：

<AgentUiProjectionView
  state={state}
  labels={{
    messagePartsAriaLabel: t("agent.messages.aria"),
    processTimelineAriaLabel: t("agent.timeline.aria"),
    executionGraphAriaLabel: t("agent.graph.aria"),
    runtimeSummaryAriaLabel: t("agent.summary.aria"),
    actionRequiredAriaLabel: t("agent.actions.aria"),
    actionButtonLabel: (action) => t(`agent.action.${action.decision}`),
    eventStatusLabel: (event) => t(`agent.eventStatus.${event.status}`),
  }}
/>;

宿主需要覆盖 zh-CN / zh-TW / en-US / ja-JP / ko-KR，不要把本包 fallback 当成产品文案。

Source Layout

实现必须按职责拆分，src/index.ts 只能做 barrel exports：

src/types.ts           -> 公共 props / callback / message 类型
src/labels.ts          -> 默认 label、status 和 meta formatter
src/messages.tsx       -> AgentTimeline / UIMessagePartsView
src/processTimeline.tsx -> ProcessTimelineView
src/executionGraph.tsx -> ExecutionGraphView
src/refs.tsx           -> ArtifactRefList / EvidenceRefList / AgentUiRefList
src/runtimeFacts.tsx   -> RuntimeFactsPanel / RuntimeFactCard / action/tool lists
src/subagents.tsx      -> SubagentsView / SubagentThreadList / SubagentDelegationList / SubagentActivityList
src/projectionView.tsx -> AgentUiProjectionView 标准组合入口
src/index.ts           -> barrel exports only

新增 primitive 必须落在对应职责文件，或先新增职责明确的小模块；不得把实现重新合并回 src/index.ts。

CSS Contract

组件只输出稳定 class names，不注入全局样式。宿主应用应按自己的设计语言提供样式。

核心 class names：

• agent-turn
• agent-turn user
• agent-turn assistant
• agent-turn-avatar
• agent-turn-body
• agent-turn-head
• agent-turn-model
• agent-turn-details
• agent-message-parts
• agent-message-part
• agent-empty-session
• agent-runtime-event
• agent-runtime-summary
• agent-process-timeline
• agent-process-entry
• agent-execution-events
• agent-tool-group
• agent-action-required-list
• agent-subagents
• agent-subagent-threads
• agent-subagent-thread
• agent-subagent-delegations
• agent-subagent-delegation
• agent-subagent-activities
• agent-subagent-activity
• agent-ref-list
• agent-ref-card
• agent-ref-action
• agent-artifact-refs
• agent-evidence-refs
• agent-execution-graph
• agent-execution-node
• agent-event-surface
• agent-event-action
• agent-event-actions
• agent-session-artifact
• agent-ui-projection class name
• agent-ui-main
• agent-ui-sidecar

这些 class names 是包级 CSS contract。宿主应用可以用自己的设计系统实现样式，不应把样式文件或页面壳反向变成包依赖。

稳定 data attributes：

| Attribute | Surface | 用途 | | --- | --- | --- | | data-runtime-status | AgentUiProjectionView | 当前 runtime status。 | | data-hydration-status | AgentUiProjectionView | hydration / stale / repair 状态。 | | data-action-decision | action buttons | approve / reject / answer / retry 等 action intent。 | | data-node-id / data-node-type / data-parent-id | graph | graph node 和 lineage。 | | data-subagent-count / data-delegation-count / data-activity-count | Subagents | 子代理 smoke / snapshot 断言。 | | data-thread-id / data-subagent-id / data-parent-thread-id | Subagents | 子代理线程身份和父子关系。 | | data-delegation-action / data-target-thread-ids | Subagents | 委派调用类型和目标线程。 | | data-activity-kind / data-source-event-id | Subagents | 活动分类和来源事件。 | | data-event-class | runtime fact cards | tool.*、handoff.*、review.* 等事件族。 | | data-ref-kind / data-ref-id / data-source-event-id | artifact / evidence refs | 引用类型、引用 id 和来源事件。 |

Accessibility

默认 aria label 只是 fallback。产品应用必须通过 labels 注入本地化 aria label，并确保可点击 action 使用真实 <button>。组件不会把图标、颜色或状态文本作为唯一语义；状态同时通过 class / data attributes 暴露给宿主样式和测试。

Backend Integration

推荐数据流：

App Server JSON-RPC
  -> host app service/store
  -> executionEvents
  -> @limecloud/agent-ui-contracts
  -> @limecloud/agent-runtime-projection
  -> @limecloud/agent-runtime-ui
  -> host app action resolver

新页面默认使用 projectAgentUiState(...) -> AgentUiProjectionView。如果宿主只需要旧事实栏，可以继续使用 projectAgentRuntimeReadModel(...) -> RuntimeFactsPanel；这属于兼容入口，不是新增 surface 的默认路径。

onResolveAction 只返回用户意图，不直接处理后端：

<RuntimeFactsPanel
  readModel={readModel}
  onResolveAction={(event, action) => {
    if (action.decision === "open-model-settings") {
      openSettings();
    }
  }}
/>

RuntimeFactsPanel 只渲染宿主传入的 read model，不会订阅 JSON-RPC，也不会判断某个 artifact 是否已经被业务层物化。宿主如果已经把 App Server artifact.snapshot 写成业务产物，应在进入 @limecloud/agent-runtime-projection 前去掉上游快照事件，只保留本地业务产物的 artifact.changed。这样右侧事实栏展示的是可继续编辑、可应用的交付物，而不是后端中间事件。

Product App Pattern

产品应用通常这样接入：

function ProductAgentPanel({ sessionId }: { sessionId: string }) {
  const runtime = useAgentRuntimeClient();
  const facts = useAgentRuntimeFacts(sessionId);
  const state = projectAgentUiState({
    executionEvents: facts.executionEvents,
    sourceCount: facts.sourceCount,
  });

  return (
    <AgentUiProjectionView
      state={state}
      artifact={<ProductArtifactWorkspace sessionId={sessionId} />}
      onResolveAction={(event, action) => {
        runtime.respondAction({
          sessionId,
          requestId: event.actionId ?? event.id,
          actionType: "ask_user",
          confirmed: action.decision !== "reject",
          response: action.decision,
        });
      }}
      labels={productAgentLabels}
    />
  );
}

这段模式里，UI 包只负责渲染和回调。useAgentRuntimeClient、useAgentRuntimeFacts、业务 artifact workspace、权限判断和路由都属于宿主。

Subagents 的接入也必须走标准 projection state：

import { SubagentsView } from "@limecloud/agent-runtime-ui";

<SubagentsView
  state={state}
  labels={{
    subagentsAriaLabel: t("agent.subagents"),
    subagentThreadsAriaLabel: t("agent.subagents.threads"),
    subagentDelegationsAriaLabel: t("agent.subagents.delegations"),
    subagentActivitiesAriaLabel: t("agent.subagents.activities"),
  }}
/>;

SubagentsView 只读取 state.subagents。如果业务组件需要自定义子代理布局，也应消费同一个模型，而不是重新过滤 state.graph 或 state.readModel.visibleEvents。

Testing

React surface 测试应使用 contracts fixture 和 projection replay，不要自己编私有状态：

import { renderToStaticMarkup } from "react-dom/server";
import { getAgentUiFixture } from "@limecloud/agent-ui-contracts";
import { replayAgentUiFixture } from "@limecloud/agent-runtime-projection";
import { AgentUiProjectionView } from "@limecloud/agent-runtime-ui";

const replay = replayAgentUiFixture(getAgentUiFixture("hitl-action"));
const html = renderToStaticMarkup(
  <AgentUiProjectionView state={replay.state} />,
);

expect(html).toContain("data-action-decision");

组件测试只覆盖渲染、class / data attribute contract 和 callback 接线。复杂状态机、事件归并和 summary 归类应在 projection 包测试。

标准 fixture smoke 至少覆盖：

• hitl-action 渲染 data-action-decision。
• tool-success / tool-failure 渲染 ToolGroup。
• artifact-evidence 渲染 artifact / evidence refs。
• subagent-handoff 渲染 SubagentsView、threads、delegation calls、activities。

Development

npm --prefix packages/agent-runtime-projection run build
npm --prefix packages/agent-runtime-ui run build
npm --prefix packages/agent-runtime-ui run test
npm --prefix packages/agent-runtime-ui pack --dry-run

Package Metadata

| Item | Value | | --- | --- | | Runtime | Node >=20，ESM。 | | Peer deps | react >=18 <20、react-dom >=18 <20。 | | Dependencies | @limecloud/agent-ui-contracts。 | | Dev dependency | @limecloud/agent-runtime-projection 仅用于 fixture replay 测试。 | | Side effects | false，不注入全局 CSS。 | | Public files | dist、README.md。 | | License | MIT。 |

Do Not

• 不要在本包里创建 runtime client、订阅 JSON-RPC、调用 Electron bridge 或访问 App Server。
• 不要在本包里拼 Provider 参数、读取 API key、解释 tool lifecycle 或合成 evidence。
• 不要把业务页面、workspace、Prompt 草稿、素材预览或审核流放进共享 UI 包。
• 不要在 React 组件里重写 projection reducer、scope selector、summary selector 或 runtime facts 解释。
• 不要让默认英文 fallback 进入 Lime 产品文案；产品应用必须注入本地化 label。

Publish

首次发布到 npmjs：

npm --prefix packages/agent-runtime-ui publish --access public

发布前必须先发布同版本的 @limecloud/agent-runtime-projection，并确认 npm pack --dry-run 输出只包含 dist 和 README.md。