♻️ refactor(agent): rename WorkingDirectoryBar to HeteroControlBar

Make the heterogeneous chat-input bar a symmetric sibling of ControlBar:
both compose the shared WorkspaceControls, so naming should match. Rename
the file, component and displayName, and update the controlBarSlot usage.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.agents/skills/agent-runtime-hooks/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-runtime-hooks
-description: "Agent runtime lifecycle hooks for observing and intercepting agent execution. Use when adding hooks to agent operations, mocking tool calls, logging step events, handling human intervention, sub-agent calls, context compression, or building eval/tracing integrations. Triggers on 'hooks', 'beforeToolCall', 'afterToolCall', 'beforeStep', 'afterStep', 'onComplete', 'onError', 'tool mock', 'agent lifecycle', 'human intervention', 'callAgent', 'compact'."
+description: 'Agent runtime lifecycle hooks. Use for before/after tool or step hooks, tool mocks, human intervention, sub-agent calls, context compression, evals, tracing, callAgent, or lifecycle events.'
 user-invocable: false
 ---
 

.agents/skills/agent-signal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-signal
-description: Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by event sources, semantic signals, and action handlers. Use when adding a new Agent Signal source, signal or action type, policy, middleware handler, workflow handoff, dedupe or scope behavior, or observability around `src/server/services/agentSignal/**`, `packages/agent-signal`, or `packages/observability-otel/src/modules/agent-signal`.
+description: 'Build or extend LobeHub Agent Signal pipelines. Use for signal sources, signal/action types, policies, middleware, workflow handoff, dedupe, scope behavior, or observability.'
 ---
 
 # Agent Signal

.agents/skills/agent-tracing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-tracing
-description: "Agent tracing CLI for inspecting agent execution snapshots. Use when user mentions 'agent-tracing', 'trace', 'snapshot', wants to debug agent execution, inspect LLM calls, view context engine data, or analyze agent steps. Triggers on agent debugging, trace inspection, or execution analysis tasks."
+description: 'Agent tracing CLI for execution snapshots. Use for agent-tracing, traces, snapshots, LLM call inspection, context engine data, agent step analysis, or execution debugging.'
 user-invocable: false
 ---
 

.agents/skills/builtin-tool/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: builtin-tool
-description: Build a new builtin tool package under `packages/builtin-tool-<name>/`. Use when adding a new agent-callable toolset, designing its API surface (manifest / ApiName / Params / State), implementing the Executor + ExecutionRuntime, building the Inspector / Render / Placeholder / Streaming / Intervention / Portal UI, or wiring a tool into the central registries (`packages/builtin-tools/src/{index,identifiers,inspectors,renders,placeholders,streamings,interventions,portals}.ts` and `src/store/tool/slices/builtin/executors/index.ts`). Triggers on "new builtin tool", "add a tool", "tool inspector", "tool render", "tool placeholder", "tool streaming", "tool intervention", "BuiltinToolManifest", "BaseExecutor", "ExecutionRuntime".
+description: 'Build LobeHub builtin tool packages. Use when adding agent-callable tools, manifests, executors, runtimes, inspectors, renders, placeholders, streaming, interventions, portals, or tool registries.'
 ---
 
 # Builtin Tool Authoring Guide
@@ -23,7 +23,7 @@ A builtin tool is a package the agent runtime can call. It ships **five faces**:
 | ------------------------------------------------------------------------------------ | --------------------------------------------- |
 | Where do files live? What does each face do? Wiring?                                 | [architecture.md](references/architecture.md) |
 | How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](references/tool-design.md)   |
-| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui.md](references/ui.md)                     |
+| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui/](references/ui/README.md)                |
 
 ---
 

.agents/skills/builtin-tool/references/tool-design.md

@@ -2,7 +2,7 @@
 
 This doc covers everything that **isn't UI**: the tool's identifier, API surface, manifest, types, system prompt, ExecutionRuntime, and the executor that wires it into the frontend.
 
-For UI surfaces (Inspector / Render / Placeholder / Streaming / Intervention / Portal), see [ui.md](ui.md).
+For UI surfaces (Inspector / Render / Placeholder / Streaming / Intervention / Portal), see [ui/](ui/README.md).
 For where files live and how registries work, see [architecture.md](architecture.md).
 
 ---
@@ -156,7 +156,7 @@ export const TaskManifest: BuiltinToolManifest = {
   executors: ['client', 'server'],
 
   /* Default human intervention policy for all APIs that don't specify one.
-     Pair with an Intervention component (see ui.md). */
+     Pair with an Intervention component (see ui/intervention.md). */
   humanIntervention: 'never' | 'always' | { /* extended config */ },
 }
 ```

.agents/skills/builtin-tool/references/ui.md

@@ -1,744 +0,0 @@
-# Tool UI Surfaces
-
-A builtin tool can ship up to **six client-side surfaces**, each with a different role in the chat UI. Only `Inspector` is required; the other five are added on demand and registered in their own central files.
-
-| Surface      | Required? | When the chat shows it                                                | Registered in                                 |
-| ------------ | --------- | --------------------------------------------------------------------- | --------------------------------------------- |
-| Inspector    | ✅ Always | Header strip of every tool call (one-line chip)                       | `packages/builtin-tools/src/inspectors.ts`    |
-| Render       | Optional  | Rich result card below the header, after the call returns             | `packages/builtin-tools/src/renders.ts`       |
-| Placeholder  | Optional  | Skeleton between "args streaming complete" and "result arrives"       | `packages/builtin-tools/src/placeholders.ts`  |
-| Streaming    | Optional  | Live output during execution (e.g. command stdout)                    | `packages/builtin-tools/src/streamings.ts`    |
-| Intervention | Optional  | Approval / edit-before-run dialog (when `humanIntervention` triggers) | `packages/builtin-tools/src/interventions.ts` |
-| Portal       | Optional  | Full-screen detail view (right-side or modal)                         | `packages/builtin-tools/src/portals.ts`       |
-
-The two reference tools to read end-to-end:
-
-- **`builtin-tool-web-browsing/src/client/`** — Inspector + Render + Placeholder + Portal (no Intervention/Streaming).
-- **`builtin-tool-local-system/src/client/`** — all six surfaces, including `components/` for shared building blocks.
-
----
-
-## Tool Render 设计原则（中文草案）
-
-这些原则用于判断一个 builtin tool 的 Inspector / Render / Placeholder / Streaming / Intervention / Portal 应该做什么，以及做到什么程度。
-
-1. **先保证折叠态可读。** 每个 API 都必须有 Inspector；用户不展开也应该能看懂 “正在做什么 / 对什么做 / 当前结果是什么”。Inspector 不应该只展示函数名和原始参数。
-2. **Inspector 是一句话，不是详情页。** 优先表达动作、关键对象、数量、状态，例如 “分析图片 3 张”“搜索 12 个结果”“读取 config.json”。长文本、列表和结构化结果放到 Render 或 Portal。
-3. **Inspector 要覆盖执行生命周期。** `args` 还在 streaming、工具执行中、执行完成、执行失败时都应该有稳定展示；必要时同时读取 `args`、`partialArgs` 和 `pluginState`，避免出现空白、跳变或只显示半截参数。
-4. **文案要随状态切换时态。** 同一个动作在 loading 与 completed 两个阶段必须用不同的措辞：执行中用现在进行时（“正在创建任务 / Creating task / 正在搜索”），执行完成后切到完成态（“已创建任务 / Task created / 已找到 N 条”）。Inspector chip 会一直留在聊天记录里 —— 如果一直挂着 “正在 xxx”，几小时后回看历史时会读起来像还在跑。约定的 i18n 形式是 `<api>.loading` / `<api>.completed` 一对键（见 `lobe-agent.apiName.callSubAgent.{loading,completed}` 与 `lobe-claude-code.task.{create,list,update,get}.{loading,completed}`），渲染时按 `isArgumentsStreaming || isLoading` 决定取哪一个。只读 / 查询类（“查看任务” 这种本来就是名词性的）可以共用一个键。
-5. **只有结构化结果才需要 Render。** 如果工具结果只是自然语言总结，通常不需要 Render；如果结果包含列表、媒体、文件、表格、代码、diff、地图、时间线、权限请求等结构，就应该提供 Render。
-6. **Render 要帮助用户检查结果，而不是复述参数。** Render 的主体应该围绕工具产物组织：可预览、可比较、可筛选、可定位。参数只作为上下文辅助出现，不要把 Render 做成一块更大的 args dump。
-7. **参数和结果要一起参与渲染。** 好的 Tool UI 通常同时用 `args` 解释意图，用 `pluginState` 展示真实执行结果；但 `pluginState` 只放结果域数据，不要反向塞入可以从 `args` 推导出的内容。
-8. **慢操作要有 Placeholder。** 如果工具通常需要等待网络、文件系统、模型或外部进程，Placeholder 应该先占住最终 Render 的版式，让用户知道即将看到什么，而不是只显示一个泛化 loading。
-9. **Streaming 只用于连续产物。** 搜索列表、日志、长文本、文件分析、分阶段计划适合 Streaming；一次性小结果不需要强行做 Streaming。Streaming UI 要能渐进追加，并且完成后自然过渡到最终 Render。
-10. **有风险的动作必须 Intervention。** 写文件、删除、发送、安装、执行命令、外部可见操作、权限敏感操作，都应该在执行前给出可理解的确认界面；确认文案要说明影响范围，而不是只问 “是否继续”。
-11. **错误、空态和截断都是正式状态。** Render 不能在失败、无结果、超长结果时退化成空白。错误要说明发生在哪一步；空态要告诉用户没有产物；超长内容要明确 “展示前 N 项 / 还有 N 项”。
-12. **信息密度要克制。** 默认展示最有判断价值的部分：标题、来源、状态、摘要、少量关键字段。大对象、长列表、原文、调试数据放进可展开区域或 Portal，避免把聊天流撑成后台管理页。
-13. **视觉上融入聊天流。** Tool UI 应该使用 `@lobehub/ui` / base-ui、`Flexbox`、`createStaticStyles` 和 `cssVar.*`，遵循现有间距、圆角、颜色、字号；不要为单个工具发明一套独立视觉语言。
-14. **Devtools fixture 是验收入口。** 新增或修改 Tool UI 时，应在 `/devtools` 里准备覆盖典型态、loading/streaming、空态、错误态、长内容态的 fixture；一个 API 如果在真实聊天里会出现，就不应该在 devtools 中缺席。
-15. **先做用户会看的 UI，再做调试 UI。** Raw JSON、trace、schema、内部 id 可以存在，但应默认收起或放到调试区；主界面先回答用户最关心的问题：工具做了什么，结果值不值得信任，下一步能做什么。
-
----
-
-## 0. Shared Style Rules
-
-These apply across every surface.
-
-### 0.1 Use `'use client'` at the top of every component file
-
-Tool surfaces are leaves in the chat tree and must not block server rendering.
-
-### 0.2 Prefer `createStaticStyles + cssVar.*`
-
-Zero-runtime CSS-in-JS — the styles compile once and read CSS variables at runtime.
-
-```tsx
-import { createStaticStyles, cssVar } from 'antd-style';
-
-const styles = createStaticStyles(({ css, cssVar }) => ({
-  chip: css`
-    padding-block: 2px;
-    padding-inline: 8px;
-    border-radius: 999px;
-    color: ${cssVar.colorText};
-    background: ${cssVar.colorFillTertiary};
-  `,
-}));
-```
-
-Fall back to `createStyles + token` only when you need runtime token computation (rare). Inline `style={{ color: cssVar.colorTextSecondary }}` is fine for one-off dynamic values.
-
-### 0.3 Use `@lobehub/ui`, not raw `antd`
-
-`Block`, `Text`, `Flexbox`, `Highlighter`, `Alert`, `Tooltip`, `Skeleton` all come from `@lobehub/ui`. Modals come from `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
-
-Memory note: `@lobehub/ui`'s `<Text type='secondary'>` is a lighter shade than `colorTextSecondary`. If you need that exact token color, write `<Text style={{ color: cssVar.colorTextSecondary }}>`.
-
-### 0.4 Always `memo` and set `displayName`
-
-```tsx
-export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
-  ({ args /* … */ }) => {
-    /* … */
-  },
-);
-SearchInspector.displayName = 'SearchInspector';
-export default SearchInspector;
-```
-
-### 0.5 Always type with `BuiltinXProps<Args, State>` generics
-
-Don't widen to `any`. The Args generic is the JSON Schema params, the State generic is the executor's `state` field. The two should match `<Name>Params` and `<Name>State` from `types.ts`.
-
-### 0.6 Pull strings from `t('plugin')`
-
-```tsx
-const { t } = useTranslation('plugin');
-t('builtins.<identifier>.apiName.<api>');
-```
-
-Every Inspector should default to `t('builtins.<identifier>.apiName.<api>')` so it shows something while args stream in.
-
-### 0.7 Read store state from `@/store/chat`, not props
-
-Tool surfaces sometimes need cross-cutting state (loading, streaming buffer). Read it inside the component via Zustand selectors, not from props — props only carry args/state/messageId.
-
----
-
-## 1. Inspector — Header Chip (required)
-
-**Lifecycle:** Inspector renders for **every phase** of a tool call: while args are streaming in, while the executor is running, and after results come back. It's the only surface that's always visible.
-
-**Goal:** keep it to a single line. Show what's happening with as much context as is currently available.
-
-### Props (`BuiltinInspectorProps<Args, State>`)
-
-```ts
-interface BuiltinInspectorProps<Arguments = any, State = any> {
-  apiName: string;
-  args: Arguments; // final args (only after the assistant stops streaming)
-  identifier: string;
-  isArgumentsStreaming?: boolean; // args still arriving
-  isLoading?: boolean; // args complete, executor running
-  partialArgs?: Arguments; // partial JSON during streaming
-  pluginState?: State; // executor's `state` after success
-  result?: { content: string | null; error?: any };
-}
-```
-
-### State machine
-
-| Phase                               | What's available                                           | What to show                                               |
-| ----------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
-| Args streaming, no useful field yet | `isArgumentsStreaming === true`, `partialArgs.X` undefined | Just the API title with `shinyTextStyles.shinyText`        |
-| Args streaming, key field arrived   | `partialArgs.X` populated                                  | Title + key field chip, still pulse-animated               |
-| Args complete, executor running     | `args` populated, `isLoading === true`                     | Same as above, still pulse-animated                        |
-| Result arrived                      | `pluginState` populated, `isLoading === false`             | Title + chips + result summary (count, identifier, status) |
-
-### Canonical example — Search
-
-`packages/builtin-tool-web-browsing/src/client/Inspector/Search/index.tsx`:
-
-```tsx
-'use client';
-
-import type { BuiltinInspectorProps, SearchQuery, UniformSearchResponse } from '@lobechat/types';
-import { Text } from '@lobehub/ui';
-import { cssVar, cx } from 'antd-style';
-import { memo } from 'react';
-import { useTranslation } from 'react-i18next';
-
-import { highlightTextStyles, inspectorTextStyles, shinyTextStyles } from '@/styles';
-
-export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
-  ({ args, partialArgs, isArgumentsStreaming, isLoading, pluginState }) => {
-    const { t } = useTranslation('plugin');
-
-    const query = args?.query || partialArgs?.query || '';
-    const resultCount = pluginState?.results?.length ?? 0;
-    const hasResults = resultCount > 0;
-
-    if (isArgumentsStreaming && !query) {
-      return (
-        <div className={cx(inspectorTextStyles.root, shinyTextStyles.shinyText)}>
-          <span>{t('builtins.lobe-web-browsing.apiName.search')}</span>
-        </div>
-      );
-    }
-
-    return (
-      <div
-        className={cx(
-          inspectorTextStyles.root,
-          (isArgumentsStreaming || isLoading) && shinyTextStyles.shinyText,
-        )}
-      >
-        <span>{t('builtins.lobe-web-browsing.apiName.search')}:&nbsp;</span>
-        {query && <span className={highlightTextStyles.primary}>{query}</span>}
-        {!isLoading &&
-          !isArgumentsStreaming &&
-          pluginState?.results &&
-          (hasResults ? (
-            <span style={{ marginInlineStart: 4 }}>({resultCount})</span>
-          ) : (
-            <Text as="span" color={cssVar.colorTextDescription} fontSize={12}>
-              ({t('builtins.lobe-web-browsing.inspector.noResults')})
-            </Text>
-          ))}
-      </div>
-    );
-  },
-);
-SearchInspector.displayName = 'SearchInspector';
-export default SearchInspector;
-```
-
-### Inspector rules
-
-- Wrap the whole row with `inspectorTextStyles.root` (provides correct flex / line-height baseline).
-- Pulse with `shinyTextStyles.shinyText` whenever `isArgumentsStreaming || isLoading`.
-- Show the i18n title first so the row is non-empty during the earliest streaming phase.
-- Read both `args?.X` and `partialArgs?.X` together — `args` is final, `partialArgs` is in-stream.
-- Use chips/tags for distinct facets (identifier, name, parent, status, count). Each chip should clip with `text-overflow: ellipsis` and have a `max-width` so long values don't blow out the chat bubble.
-- Append `pluginState`-derived suffixes only **after** loading finishes — count or "(no results)" should not appear while still searching.
-- **Switch copy by phase.** If the verb implies an ongoing action ("Creating", "Searching", "Listing"), define `<api>.loading` and `<api>.completed` keys and select via `isArgumentsStreaming || isLoading ? loadingKey : completedKey`. Inspector chips persist in chat history — leaving "Creating task" frozen on a finished call reads as if the tool is still running. Read-only labels that are already noun-form ("View task") can keep a single key. See `CallSubAgentInspector` for the canonical two-key pattern.
-
-### Inspector registry — `client/Inspector/index.ts`
-
-```ts
-import type { BuiltinInspector } from '@lobechat/types';
-
-import { TaskApiName } from '../../types';
-import { CreateTaskInspector } from './CreateTask';
-import { ListTasksInspector } from './ListTasks';
-/* … */
-
-export const TaskInspectors: Record<string, BuiltinInspector> = {
-  [TaskApiName.createTask]: CreateTaskInspector as BuiltinInspector,
-  [TaskApiName.listTasks]: ListTasksInspector as BuiltinInspector,
-  /* one entry per ApiName */
-};
-
-export { CreateTaskInspector } from './CreateTask';
-export { ListTasksInspector } from './ListTasks';
-/* re-export each */
-```
-
----
-
-## 2. Render — Rich Result Card (optional)
-
-**Lifecycle:** rendered **once the result arrives** (after Placeholder/Streaming hand off). Sits below the Inspector header.
-
-**Skip if** the API is read-only or the result is just text — the framework already shows the executor's `content` string. Add a Render only when there's a structured artifact worth seeing: a card, a chart, a diff, a list of files.
-
-### Props (`BuiltinRenderProps<Args, State, Content>`)
-
-```ts
-interface BuiltinRenderProps<Arguments = any, State = any, Content = any> {
-  apiName?: string;
-  args: Arguments; // final params from the LLM
-  content: Content; // executor's content string (or parsed)
-  identifier?: string;
-  messageId: string; // for store lookups
-  pluginError?: any; // from BuiltinToolResult.error
-  pluginState?: State; // executor's state
-  toolCallId?: string;
-}
-```
-
-### Two patterns
-
-**Pattern A — Single-file Render** (web-browsing CrawlSinglePage):
-
-```tsx
-// client/Render/CrawlSinglePage.tsx
-import type { BuiltinRenderProps, CrawlPluginState, CrawlSinglePageQuery } from '@lobechat/types';
-import { memo } from 'react';
-
-import PageContent from './PageContent';
-
-const CrawlSinglePage = memo<BuiltinRenderProps<CrawlSinglePageQuery, CrawlPluginState>>(
-  ({ messageId, pluginState, args }) => (
-    <PageContent messageId={messageId} results={pluginState?.results} urls={[args?.url]} />
-  ),
-);
-export default CrawlSinglePage;
-```
-
-**Pattern B — Folder with subcomponents** (web-browsing Search):
-
-```
-client/Render/Search/
-├── index.tsx           # composes the subcomponents, handles error states
-├── ConfigForm.tsx      # appears when pluginError.type === 'PluginSettingsInvalid'
-├── SearchQuery.tsx     # editable query header
-└── SearchResult.tsx    # result list
-```
-
-Use Pattern B when the Render has internal state (editing mode, expanded items), error variants, or is large enough to benefit from splitting.
-
-### Error handling in Render
-
-Renders are the canonical place to surface `pluginError` because the chat doesn't auto-render typed errors:
-
-```tsx
-if (pluginError) {
-  if (pluginError?.type === 'PluginSettingsInvalid') {
-    return <ConfigForm id={messageId} provider={pluginError.body?.provider} />;
-  }
-  return (
-    <Alert
-      title={pluginError?.message}
-      type="error"
-      extra={<Highlighter language="json">{JSON.stringify(pluginError.body, null, 2)}</Highlighter>}
-    />
-  );
-}
-```
-
-### Render rules
-
-- **Return `null`** if there's nothing useful to draw yet (avoids empty cards during stream).
-- Use `pluginState` for server-truth (ids, counts, server-assigned status) and `args` for what the LLM asked. **Combine — neither alone is enough.**
-- For lists, summarize with a header line and show top N items with a "+N more" tail rather than rendering everything.
-- For modals from a Render, use `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
-
-### Render registry — `client/Render/index.ts`
-
-```ts
-import type { BuiltinRender } from '@lobechat/types';
-
-import { TaskApiName } from '../../types';
-import CreateTaskRender from './CreateTask';
-import RunTasksRender from './RunTasks';
-
-export const TaskRenders: Record<string, BuiltinRender> = {
-  [TaskApiName.createTask]: CreateTaskRender as BuiltinRender,
-  [TaskApiName.runTasks]: RunTasksRender as BuiltinRender,
-  /* only the APIs with rich result UI — others fall back to text content */
-};
-
-export { default as CreateTaskRender } from './CreateTask';
-export { default as RunTasksRender } from './RunTasks';
-```
-
-### Render display control (rare)
-
-If the Render should hide for certain results (e.g. ClaudeCode's TodoWrite hides when the agent is mid-stream), add a `RenderDisplayControl` to `packages/builtin-tools/src/displayControls.ts`. See `ClaudeCodeRenderDisplayControls` for the pattern.
-
----
-
-## 3. Placeholder — Skeleton Between Args and Result (optional)
-
-**Lifecycle:** rendered when the args have finished streaming but the executor hasn't returned yet. Disappears when `pluginState` arrives. Bridges the moment of perceived lag.
-
-**Add for** APIs with noticeable execution time: web search, network crawl, file list, large grep. **Skip for** instant ops (status flips, calculator).
-
-### Props (`BuiltinPlaceholderProps<Args>`)
-
-```ts
-interface BuiltinPlaceholderProps<T extends Record<string, any> = any> {
-  apiName: string;
-  args?: T;
-  identifier: string;
-}
-```
-
-No `pluginState` — Placeholder lives entirely in the "executing" gap.
-
-### Canonical example — Search Placeholder
-
-`packages/builtin-tool-web-browsing/src/client/Placeholder/Search.tsx`:
-
-```tsx
-import type { BuiltinPlaceholderProps, SearchQuery } from '@lobechat/types';
-import { Flexbox, Icon, Skeleton } from '@lobehub/ui';
-import { createStaticStyles, cx } from 'antd-style';
-import { SearchIcon } from 'lucide-react';
-import { memo } from 'react';
-
-import { useIsMobile } from '@/hooks/useIsMobile';
-import { shinyTextStyles } from '@/styles';
-
-const styles = createStaticStyles(({ css, cssVar }) => ({
-  query: cx(
-    css`
-      padding: 4px 8px;
-      border-radius: 8px;
-      font-size: 12px;
-      color: ${cssVar.colorTextSecondary};
-      &:hover {
-        background: ${cssVar.colorFillTertiary};
-      }
-    `,
-    shinyTextStyles.shinyText,
-  ),
-}));
-
-export const Search = memo<BuiltinPlaceholderProps<SearchQuery>>(({ args }) => {
-  const { query } = args || {};
-  const isMobile = useIsMobile();
-
-  return (
-    <Flexbox gap={8}>
-      <Flexbox horizontal={!isMobile} gap={isMobile ? 8 : 40}>
-        <Flexbox horizontal align="center" className={styles.query} gap={8}>
-          <Icon icon={SearchIcon} />
-          {query ? query : <Skeleton.Block active style={{ height: 20, width: 40 }} />}
-        </Flexbox>
-        <Skeleton.Block active style={{ height: 20, width: 40 }} />
-      </Flexbox>
-      <Flexbox horizontal gap={12}>
-        {[1, 2, 3, 4, 5].map((id) => (
-          <Skeleton.Button active key={id} style={{ borderRadius: 8, height: 80, width: 160 }} />
-        ))}
-      </Flexbox>
-    </Flexbox>
-  );
-});
-```
-
-### Placeholder rules
-
-- **Mirror the eventual Render's layout.** When the result arrives the Placeholder unmounts and the Render mounts; if they share dimensions, the chat doesn't jump.
-- Use `Skeleton.Block` / `Skeleton.Button` from `@lobehub/ui` for placeholder shapes.
-- Embed any args you have (e.g. the query text) — context helps the user know what's loading.
-- Pulse with `shinyTextStyles.shinyText` if the Placeholder includes literal text.
-
-### Placeholder registry — `client/Placeholder/index.ts`
-
-```ts
-import { WebBrowsingApiName } from '../../types';
-import CrawlMultiPages from './CrawlMultiPages';
-import CrawlSinglePage from './CrawlSinglePage';
-import { Search } from './Search';
-
-export const WebBrowsingPlaceholders = {
-  [WebBrowsingApiName.crawlMultiPages]: CrawlMultiPages,
-  [WebBrowsingApiName.crawlSinglePage]: CrawlSinglePage,
-  [WebBrowsingApiName.search]: Search,
-};
-
-export { CrawlMultiPages, CrawlSinglePage, Search };
-```
-
----
-
-## 4. Streaming — Live Output During Execution (optional)
-
-**Lifecycle:** rendered **while the executor is still running** for APIs that emit incremental output. The component is responsible for fetching the in-flight stream from the chat store and rendering it.
-
-**Add for** long-running ops with continuous output: shell command execution (stdout/stderr), file write progress, code interpreter cells.
-
-### Props (`BuiltinStreamingProps<Args>`)
-
-```ts
-interface BuiltinStreamingProps<Arguments = any> {
-  apiName: string;
-  args: Arguments;
-  identifier: string;
-  messageId: string; // use to fetch the streaming buffer from store
-  toolCallId: string;
-}
-```
-
-Note there's **no `state` or `result` prop** — the Streaming component is for the in-flight phase. It pulls the live buffer from the store itself (typically via `chatToolSelectors.streamingContent(messageId)` or similar).
-
-### Canonical example — RunCommandStreaming
-
-`packages/builtin-tool-local-system/src/client/Streaming/RunCommand/index.tsx`:
-
-```tsx
-'use client';
-
-import type { BuiltinStreamingProps } from '@lobechat/types';
-import { Highlighter } from '@lobehub/ui';
-import { memo } from 'react';
-
-interface RunCommandParams {
-  command?: string;
-  description?: string;
-  timeout?: number;
-}
-
-export const RunCommandStreaming = memo<BuiltinStreamingProps<RunCommandParams>>(({ args }) => {
-  const { command } = args || {};
-  if (!command) return null;
-
-  return (
-    <Highlighter
-      animated
-      wrap
-      language="sh"
-      showLanguage={false}
-      style={{ padding: '4px 8px' }}
-      variant="outlined"
-    >
-      {command}
-    </Highlighter>
-  );
-});
-RunCommandStreaming.displayName = 'RunCommandStreaming';
-```
-
-For real-time output beyond just the command (stderr/stdout streaming), pull from the chat store:
-
-```tsx
-const buffer = useChatStore((state) =>
-  chatToolSelectors.streamingBuffer(messageId, toolCallId)(state),
-);
-```
-
-### Streaming rules
-
-- Render `null` until you have something to display (avoids flash).
-- For terminal-style output, use `Highlighter` with `animated` to show typing-like effect.
-- The Streaming component must **unmount cleanly** when execution ends — typically the framework swaps it out for the Render automatically.
-
-### Streaming registry — `client/Streaming/index.ts`
-
-```ts
-import { LocalSystemApiName } from '../..';
-import { RunCommandStreaming } from './RunCommand';
-import { WriteFileStreaming } from './WriteFile';
-
-export const LocalSystemStreamings = {
-  [LocalSystemApiName.runCommand]: RunCommandStreaming,
-  [LocalSystemApiName.writeLocalFile]: WriteFileStreaming,
-};
-```
-
----
-
-## 5. Intervention — Approval / Edit-Before-Run (optional)
-
-**Lifecycle:** rendered **before the executor runs** for APIs whose manifest sets `humanIntervention`. The user sees a preview of the args, can edit them, then approves or skips/cancels.
-
-**Add for** destructive or sensitive ops: shell commands, file writes, file moves, payments, message broadcasts.
-
-### Props (`BuiltinInterventionProps<Args>`)
-
-```ts
-interface BuiltinInterventionProps<Arguments = any> {
-  apiName?: string;
-  args: Arguments;
-  identifier?: string;
-  interactionMode?: 'approval' | 'custom';
-  messageId: string;
-
-  /** Called when the user edits the args; the approve action awaits this. */
-  onArgsChange?: (args: Arguments) => void | Promise<void>;
-
-  /** Called on approve / skip / cancel. */
-  onInteractionAction?: (
-    action:
-      | { type: 'submit'; payload: Record<string, unknown> }
-      | { type: 'skip'; payload?: Record<string, unknown>; reason?: string }
-      | { type: 'cancel'; payload?: Record<string, unknown> },
-  ) => Promise<void>;
-
-  /** Register a callback to flush pending saves before approval. Returns cleanup. */
-  registerBeforeApprove?: (id: string, callback: () => void | Promise<void>) => () => void;
-}
-```
-
-### Canonical example — RunCommand Intervention
-
-`packages/builtin-tool-local-system/src/client/Intervention/RunCommand/index.tsx`:
-
-```tsx
-import type { RunCommandParams } from '@lobechat/electron-client-ipc';
-import type { BuiltinInterventionProps } from '@lobechat/types';
-import { Flexbox, Highlighter, Text } from '@lobehub/ui';
-import { memo } from 'react';
-
-const RunCommand = memo<BuiltinInterventionProps<RunCommandParams>>(({ args }) => {
-  const { description, command, timeout } = args;
-  return (
-    <Flexbox gap={8}>
-      <Flexbox horizontal justify="space-between">
-        {description && <Text>{description}</Text>}
-        {timeout && (
-          <Text style={{ fontSize: 12 }} type="secondary">
-            timeout: {formatTimeout(timeout)}
-          </Text>
-        )}
-      </Flexbox>
-      {command && (
-        <Highlighter wrap language="sh" showLanguage={false} variant="outlined">
-          {command}
-        </Highlighter>
-      )}
-    </Flexbox>
-  );
-});
-export default RunCommand;
-```
-
-### Intervention rules
-
-- **Show a preview, not a form by default.** Editing UI is opt-in via `onArgsChange` and is usually inline (click to edit a code block, etc.).
-- For args with debounced edit state (text fields), use `registerBeforeApprove(id, flushFn)` so the approve action waits for the debounce to flush. Always return the cleanup function.
-- Call `onInteractionAction({ type: 'submit', payload })` when the user approves; `'skip'` if they skip with a reason; `'cancel'` if they cancel the whole turn.
-- Add a corresponding `interventionAudit.ts` in the package root if the tool needs scope/path validation before approval (see `local-system/src/interventionAudit.ts`).
-
-### Intervention registry — `client/Intervention/index.ts`
-
-```ts
-import { LocalSystemApiName } from '../..';
-import EditLocalFile from './EditLocalFile';
-import RunCommand from './RunCommand';
-import WriteFile from './WriteFile';
-/* … */
-
-export const LocalSystemInterventions = {
-  [LocalSystemApiName.editLocalFile]: EditLocalFile,
-  [LocalSystemApiName.runCommand]: RunCommand,
-  [LocalSystemApiName.writeLocalFile]: WriteFile,
-  /* one entry per API that needs approval */
-};
-```
-
----
-
-## 6. Portal — Full-Screen Detail View (optional)
-
-**Lifecycle:** rendered when the user opens the tool message in a side panel or full-screen modal. One Portal per **tool**, not per API — the Portal switches on `apiName` internally.
-
-**Add for** tools whose results deserve a deep-dive view: search results with editable filters, page content with reader mode, code interpreter sessions.
-
-### Props (`BuiltinPortalProps<Args, State>`)
-
-```ts
-interface BuiltinPortalProps<Arguments = Record<string, any>, State = any> {
-  apiName?: string;
-  arguments: Arguments;
-  identifier: string;
-  messageId: string;
-  state: State;
-}
-```
-
-### Canonical example — Web-Browsing Portal
-
-`packages/builtin-tool-web-browsing/src/client/Portal/index.tsx`:
-
-```tsx
-import type { BuiltinPortalProps, CrawlPluginState, SearchQuery } from '@lobechat/types';
-import { memo } from 'react';
-
-import { WebBrowsingApiName } from '../../types';
-import PageContent from './PageContent';
-import PageContents from './PageContents';
-import Search from './Search';
-
-const Portal = memo<BuiltinPortalProps>(({ arguments: args, messageId, state, apiName }) => {
-  switch (apiName) {
-    case WebBrowsingApiName.search:
-      return <Search messageId={messageId} query={args as SearchQuery} response={state} />;
-
-    case WebBrowsingApiName.crawlSinglePage: {
-      const result = (state as CrawlPluginState).results.find((r) => r.originalUrl === args.url);
-      return <PageContent messageId={messageId} result={result} />;
-    }
-
-    case WebBrowsingApiName.crawlMultiPages:
-      return (
-        <PageContents
-          messageId={messageId}
-          results={(state as CrawlPluginState).results}
-          urls={args.urls}
-        />
-      );
-  }
-  return null;
-});
-export default Portal;
-```
-
-### Portal rules
-
-- One Portal per tool — the file is the routing layer, subcomponents implement each API's view.
-- Portals can read the chat store directly to detect "still streaming" and render a Skeleton internally (see `Search/index.tsx:20-46`).
-- Layout assumes more space than the Render — use `Flexbox` with `height={'100%'}` and structure for a side panel viewport.
-
-### Portal registry — `packages/builtin-tools/src/portals.ts`
-
-```ts
-import { WebBrowsingManifest, WebBrowsingPortal } from '@lobechat/builtin-tool-web-browsing/client';
-import { type BuiltinPortal } from '@lobechat/types';
-
-export const BuiltinToolsPortals: Record<string, BuiltinPortal> = {
-  [WebBrowsingManifest.identifier]: WebBrowsingPortal as BuiltinPortal,
-};
-```
-
----
-
-## 7. `client/components/` — Shared Subcomponents
-
-Cross-cutting building blocks used by multiple surfaces live here, not duplicated in each surface folder.
-
-Examples from `web-browsing/src/client/components/`:
-
-- `CategoryAvatar.tsx` — search category icon
-- `EngineAvatar.tsx` — search engine logo (used in Inspector chip + Render list + Portal header)
-- `SearchBar.tsx` — editable query bar (used in Render and Portal)
-
-Examples from `local-system/src/client/components/`:
-
-- `FileItem.tsx` — single file row (used in ListFiles Render, SearchFiles Render, MoveLocalFiles Render)
-- `FilePathDisplay.tsx` — path with truncation (used everywhere)
-
-### Rules
-
-- Live under `client/components/`, exported via `client/components/index.ts`.
-- Re-export from `client/index.ts` only if other packages need them; otherwise keep internal.
-- Keep them dumb — props in, JSX out, no store reads. The store reads belong in the surface that composes them.
-
----
-
-## 8. `client/index.ts` — Package Public API
-
-Re-exports everything the registries need plus useful types/manifest:
-
-```ts
-// Inspector — required
-export { TaskInspectors } from './Inspector';
-
-// Render — only if any API has one
-export { TaskRenders, CreateTaskRender, RunTasksRender } from './Render';
-
-// Placeholder / Streaming / Intervention — only if used
-export { LocalSystemListFilesPlaceholder, LocalSystemSearchFilesPlaceholder } from './Placeholder';
-export { LocalSystemStreamings } from './Streaming';
-export { LocalSystemInterventions } from './Intervention';
-
-// Portal — single export per tool
-export { default as WebBrowsingPortal } from './Portal';
-
-// Reusable components if other packages need them
-export { CategoryAvatar, EngineAvatar, SearchBar } from './components';
-
-// Re-export manifest, identifier, types for convenience
-export { TaskManifest, TaskIdentifier } from '../manifest';
-export * from '../types';
-```
-
----
-
-## 9. Diagnostic Quick-Lookup
-
-| Symptom                                         | Surface to check                                                                                                  |     |                           |
-| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --- | ------------------------- |
-| No header at all on the tool call               | Inspector missing from `client/Inspector/index.ts` registry                                                       |     |                           |
-| Header shows the API name but no chips          | Inspector missing \`args?.X                                                                                       |     | partialArgs?.X\` fallback |
-| Header doesn't pulse during loading             | Missing `shinyTextStyles.shinyText` on `isArgumentsStreaming \|\| isLoading`                                      |     |                           |
-| Empty result card under header                  | Render returned `<div />` instead of `null` when no data                                                          |     |                           |
-| Layout jump when result arrives                 | Placeholder dimensions don't match Render dimensions                                                              |     |                           |
-| Approval dialog never appears                   | Manifest missing `humanIntervention`, or Intervention not in registry                                             |     |                           |
-| Approval click doesn't wait for inline edit     | Missing `registerBeforeApprove(id, flushFn)`                                                                      |     |                           |
-| Portal opens but blank                          | Switch in `Portal/index.tsx` doesn't cover the apiName                                                            |     |                           |
-| Strings show as `builtins.lobe-foo.apiName.bar` | Missing i18n key in `src/locales/default/plugin.ts` (or not seeded in dev locale files)                           |     |                           |
-| Wrong color shade on `<Text type="secondary">`  | `type='secondary'` is lighter than `colorTextSecondary` — pass via `style={{ color: cssVar.colorTextSecondary }}` |     |                           |

.agents/skills/builtin-tool/references/ui/README.md

@@ -0,0 +1,36 @@
+# Tool UI Surfaces
+
+A builtin tool can ship up to **six client-side surfaces**, each with a different role in the chat UI. Only `Inspector` is required; the other five are added on demand and registered in their own central files.
+
+| Surface      | Required? | When the chat shows it                                                | Registered in                                 |
+| ------------ | --------- | --------------------------------------------------------------------- | --------------------------------------------- |
+| Inspector    | ✅ Always | Header strip of every tool call (one-line chip)                       | `packages/builtin-tools/src/inspectors.ts`    |
+| Render       | Optional  | Rich result card below the header, after the call returns             | `packages/builtin-tools/src/renders.ts`       |
+| Placeholder  | Optional  | Skeleton between "args streaming complete" and "result arrives"       | `packages/builtin-tools/src/placeholders.ts`  |
+| Streaming    | Optional  | Live output during execution (e.g. command stdout)                    | `packages/builtin-tools/src/streamings.ts`    |
+| Intervention | Optional  | Approval / edit-before-run dialog (when `humanIntervention` triggers) | `packages/builtin-tools/src/interventions.ts` |
+| Portal       | Optional  | Full-screen detail view (right-side or modal)                         | `packages/builtin-tools/src/portals.ts`       |
+
+The two reference tools to read end-to-end:
+
+- **`builtin-tool-web-browsing/src/client/`** — Inspector + Render + Placeholder + Portal (no Intervention/Streaming).
+- **`builtin-tool-local-system/src/client/`** — all six surfaces, including `components/` for shared building blocks.
+
+---
+
+## Files in this folder
+
+Read **principles** and **shared-rules** first — they apply to every surface. Then jump to the surface you're building.
+
+| File                               | What it covers                                                          |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| [principles.md](principles.md)     | Design principles — when each surface exists and how far to take it     |
+| [shared-rules.md](shared-rules.md) | Cross-surface rules: component skeleton, styling, single-layer surfaces |
+| [inspector.md](inspector.md)       | Inspector — header chip (required)                                      |
+| [render.md](render.md)             | Render — rich result card                                               |
+| [placeholder.md](placeholder.md)   | Placeholder — skeleton between args and result                          |
+| [streaming.md](streaming.md)       | Streaming — live output during execution                                |
+| [intervention.md](intervention.md) | Intervention — approval / edit-before-run                               |
+| [portal.md](portal.md)             | Portal — full-screen detail view                                        |
+| [composition.md](composition.md)   | Shared subcomponents (`client/components/`) + package public API        |
+| [diagnostics.md](diagnostics.md)   | Symptom → surface quick-lookup                                          |

.agents/skills/builtin-tool/references/ui/composition.md

@@ -0,0 +1,51 @@
+# Composition — Shared Components & Package API
+
+## `client/components/` — Shared Subcomponents
+
+Cross-cutting building blocks used by multiple surfaces live here, not duplicated in each surface folder.
+
+Examples from `web-browsing/src/client/components/`:
+
+- `CategoryAvatar.tsx` — search category icon
+- `EngineAvatar.tsx` — search engine logo (used in Inspector chip + Render list + Portal header)
+- `SearchBar.tsx` — editable query bar (used in Render and Portal)
+
+Examples from `local-system/src/client/components/`:
+
+- `FileItem.tsx` — single file row (used in ListFiles Render, SearchFiles Render, MoveLocalFiles Render)
+- `FilePathDisplay.tsx` — path with truncation (used everywhere)
+
+### Rules
+
+- Live under `client/components/`, exported via `client/components/index.ts`.
+- Re-export from `client/index.ts` only if other packages need them; otherwise keep internal.
+- Keep them dumb — props in, JSX out, no store reads. The store reads belong in the surface that composes them.
+
+---
+
+## `client/index.ts` — Package Public API
+
+Re-exports everything the registries need plus useful types/manifest:
+
+```ts
+// Inspector — required
+export { TaskInspectors } from './Inspector';
+
+// Render — only if any API has one
+export { TaskRenders, CreateTaskRender, RunTasksRender } from './Render';
+
+// Placeholder / Streaming / Intervention — only if used
+export { LocalSystemListFilesPlaceholder, LocalSystemSearchFilesPlaceholder } from './Placeholder';
+export { LocalSystemStreamings } from './Streaming';
+export { LocalSystemInterventions } from './Intervention';
+
+// Portal — single export per tool
+export { default as WebBrowsingPortal } from './Portal';
+
+// Reusable components if other packages need them
+export { CategoryAvatar, EngineAvatar, SearchBar } from './components';
+
+// Re-export manifest, identifier, types for convenience
+export { TaskManifest, TaskIdentifier } from '../manifest';
+export * from '../types';
+```

.agents/skills/builtin-tool/references/ui/diagnostics.md

@@ -0,0 +1,15 @@
+# Diagnostic Quick-Lookup
+
+| Symptom                                         | Surface to check                                                                                                                      |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| No header at all on the tool call               | Inspector missing from `client/Inspector/index.ts` registry                                                                           |
+| Header shows the API name but no chips          | Inspector missing `args?.X \|\| partialArgs?.X` fallback                                                                              |
+| Header doesn't pulse during loading             | Missing `shinyTextStyles.shinyText` on `isArgumentsStreaming \|\| isLoading`                                                          |
+| Empty result card under header                  | Render returned `<div />` instead of `null` when no data                                                                              |
+| Render looks "complex" / card-in-card           | Filled container (`colorFillQuaternary`) wrapping more filled boxes — flatten to single-layer, see [shared-rules.md](shared-rules.md) |
+| Layout jump when result arrives                 | Placeholder dimensions don't match Render dimensions                                                                                  |
+| Approval dialog never appears                   | Manifest missing `humanIntervention`, or Intervention not in registry                                                                 |
+| Approval click doesn't wait for inline edit     | Missing `registerBeforeApprove(id, flushFn)`                                                                                          |
+| Portal opens but blank                          | Switch in `Portal/index.tsx` doesn't cover the apiName                                                                                |
+| Strings show as `builtins.lobe-foo.apiName.bar` | Missing i18n key in `src/locales/default/plugin.ts` (or not seeded in dev locale files)                                               |
+| Wrong color shade on `<Text type="secondary">`  | `type='secondary'` is lighter than `colorTextSecondary` — pass via `style={{ color: cssVar.colorTextSecondary }}`                     |

.agents/skills/builtin-tool/references/ui/inspector.md

@@ -0,0 +1,118 @@
+# Inspector — Header Chip (required)
+
+**Lifecycle:** Inspector renders for **every phase** of a tool call: while args are streaming in, while the executor is running, and after results come back. It's the only surface that's always visible.
+
+**Goal:** keep it to a single line. Show what's happening with as much context as is currently available.
+
+## Props (`BuiltinInspectorProps<Args, State>`)
+
+```ts
+interface BuiltinInspectorProps<Arguments = any, State = any> {
+  apiName: string;
+  args: Arguments; // final args (only after the assistant stops streaming)
+  identifier: string;
+  isArgumentsStreaming?: boolean; // args still arriving
+  isLoading?: boolean; // args complete, executor running
+  partialArgs?: Arguments; // partial JSON during streaming
+  pluginState?: State; // executor's `state` after success
+  result?: { content: string | null; error?: any };
+}
+```
+
+## State machine
+
+| Phase                               | What's available                                           | What to show                                               |
+| ----------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
+| Args streaming, no useful field yet | `isArgumentsStreaming === true`, `partialArgs.X` undefined | Just the API title with `shinyTextStyles.shinyText`        |
+| Args streaming, key field arrived   | `partialArgs.X` populated                                  | Title + key field chip, still pulse-animated               |
+| Args complete, executor running     | `args` populated, `isLoading === true`                     | Same as above, still pulse-animated                        |
+| Result arrived                      | `pluginState` populated, `isLoading === false`             | Title + chips + result summary (count, identifier, status) |
+
+## Canonical example — Search
+
+`packages/builtin-tool-web-browsing/src/client/Inspector/Search/index.tsx`:
+
+```tsx
+'use client';
+
+import type { BuiltinInspectorProps, SearchQuery, UniformSearchResponse } from '@lobechat/types';
+import { Text } from '@lobehub/ui';
+import { cssVar, cx } from 'antd-style';
+import { memo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { highlightTextStyles, inspectorTextStyles, shinyTextStyles } from '@/styles';
+
+export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
+  ({ args, partialArgs, isArgumentsStreaming, isLoading, pluginState }) => {
+    const { t } = useTranslation('plugin');
+
+    const query = args?.query || partialArgs?.query || '';
+    const resultCount = pluginState?.results?.length ?? 0;
+    const hasResults = resultCount > 0;
+
+    if (isArgumentsStreaming && !query) {
+      return (
+        <div className={cx(inspectorTextStyles.root, shinyTextStyles.shinyText)}>
+          <span>{t('builtins.lobe-web-browsing.apiName.search')}</span>
+        </div>
+      );
+    }
+
+    return (
+      <div
+        className={cx(
+          inspectorTextStyles.root,
+          (isArgumentsStreaming || isLoading) && shinyTextStyles.shinyText,
+        )}
+      >
+        <span>{t('builtins.lobe-web-browsing.apiName.search')}:&nbsp;</span>
+        {query && <span className={highlightTextStyles.primary}>{query}</span>}
+        {!isLoading &&
+          !isArgumentsStreaming &&
+          pluginState?.results &&
+          (hasResults ? (
+            <span style={{ marginInlineStart: 4 }}>({resultCount})</span>
+          ) : (
+            <Text as="span" color={cssVar.colorTextDescription} fontSize={12}>
+              ({t('builtins.lobe-web-browsing.inspector.noResults')})
+            </Text>
+          ))}
+      </div>
+    );
+  },
+);
+SearchInspector.displayName = 'SearchInspector';
+export default SearchInspector;
+```
+
+## Inspector rules
+
+- Wrap the whole row with `inspectorTextStyles.root` (provides correct flex / line-height baseline).
+- Pulse with `shinyTextStyles.shinyText` whenever `isArgumentsStreaming || isLoading`.
+- Show the i18n title first so the row is non-empty during the earliest streaming phase.
+- Read both `args?.X` and `partialArgs?.X` together — `args` is final, `partialArgs` is in-stream.
+- Use chips/tags for distinct facets (identifier, name, parent, status, count). Each chip should clip with `text-overflow: ellipsis` and have a `max-width` so long values don't blow out the chat bubble.
+- Append `pluginState`-derived suffixes only **after** loading finishes — count or "(no results)" should not appear while still searching.
+- **Switch copy by phase.** If the verb implies an ongoing action ("Creating", "Searching", "Listing"), define `<api>.loading` and `<api>.completed` keys and select via `isArgumentsStreaming || isLoading ? loadingKey : completedKey`. Inspector chips persist in chat history — leaving "Creating task" frozen on a finished call reads as if the tool is still running. Read-only labels that are already noun-form ("View task") can keep a single key. See `CallSubAgentInspector` for the canonical two-key pattern.
+
+## Inspector registry — `client/Inspector/index.ts`
+
+```ts
+import type { BuiltinInspector } from '@lobechat/types';
+
+import { TaskApiName } from '../../types';
+import { CreateTaskInspector } from './CreateTask';
+import { ListTasksInspector } from './ListTasks';
+/* … */
+
+export const TaskInspectors: Record<string, BuiltinInspector> = {
+  [TaskApiName.createTask]: CreateTaskInspector as BuiltinInspector,
+  [TaskApiName.listTasks]: ListTasksInspector as BuiltinInspector,
+  /* one entry per ApiName */
+};
+
+export { CreateTaskInspector } from './CreateTask';
+export { ListTasksInspector } from './ListTasks';
+/* re-export each */
+```

.agents/skills/builtin-tool/references/ui/intervention.md

@@ -0,0 +1,88 @@
+# Intervention — Approval / Edit-Before-Run (optional)
+
+**Lifecycle:** rendered **before the executor runs** for APIs whose manifest sets `humanIntervention`. The user sees a preview of the args, can edit them, then approves or skips/cancels.
+
+**Add for** destructive or sensitive ops: shell commands, file writes, file moves, payments, message broadcasts.
+
+## Props (`BuiltinInterventionProps<Args>`)
+
+```ts
+interface BuiltinInterventionProps<Arguments = any> {
+  apiName?: string;
+  args: Arguments;
+  identifier?: string;
+  interactionMode?: 'approval' | 'custom';
+  messageId: string;
+
+  /** Called when the user edits the args; the approve action awaits this. */
+  onArgsChange?: (args: Arguments) => void | Promise<void>;
+
+  /** Called on approve / skip / cancel. */
+  onInteractionAction?: (
+    action:
+      | { type: 'submit'; payload: Record<string, unknown> }
+      | { type: 'skip'; payload?: Record<string, unknown>; reason?: string }
+      | { type: 'cancel'; payload?: Record<string, unknown> },
+  ) => Promise<void>;
+
+  /** Register a callback to flush pending saves before approval. Returns cleanup. */
+  registerBeforeApprove?: (id: string, callback: () => void | Promise<void>) => () => void;
+}
+```
+
+## Canonical example — RunCommand Intervention
+
+`packages/builtin-tool-local-system/src/client/Intervention/RunCommand/index.tsx`:
+
+```tsx
+import type { RunCommandParams } from '@lobechat/electron-client-ipc';
+import type { BuiltinInterventionProps } from '@lobechat/types';
+import { Flexbox, Highlighter, Text } from '@lobehub/ui';
+import { memo } from 'react';
+
+const RunCommand = memo<BuiltinInterventionProps<RunCommandParams>>(({ args }) => {
+  const { description, command, timeout } = args;
+  return (
+    <Flexbox gap={8}>
+      <Flexbox horizontal justify="space-between">
+        {description && <Text>{description}</Text>}
+        {timeout && (
+          <Text style={{ fontSize: 12 }} type="secondary">
+            timeout: {formatTimeout(timeout)}
+          </Text>
+        )}
+      </Flexbox>
+      {command && (
+        <Highlighter wrap language="sh" showLanguage={false} variant="outlined">
+          {command}
+        </Highlighter>
+      )}
+    </Flexbox>
+  );
+});
+export default RunCommand;
+```
+
+## Intervention rules
+
+- **Show a preview, not a form by default.** Editing UI is opt-in via `onArgsChange` and is usually inline (click to edit a code block, etc.).
+- For args with debounced edit state (text fields), use `registerBeforeApprove(id, flushFn)` so the approve action waits for the debounce to flush. Always return the cleanup function.
+- Call `onInteractionAction({ type: 'submit', payload })` when the user approves; `'skip'` if they skip with a reason; `'cancel'` if they cancel the whole turn.
+- Add a corresponding `interventionAudit.ts` in the package root if the tool needs scope/path validation before approval (see `local-system/src/interventionAudit.ts`).
+
+## Intervention registry — `client/Intervention/index.ts`
+
+```ts
+import { LocalSystemApiName } from '../..';
+import EditLocalFile from './EditLocalFile';
+import RunCommand from './RunCommand';
+import WriteFile from './WriteFile';
+/* … */
+
+export const LocalSystemInterventions = {
+  [LocalSystemApiName.editLocalFile]: EditLocalFile,
+  [LocalSystemApiName.runCommand]: RunCommand,
+  [LocalSystemApiName.writeLocalFile]: WriteFile,
+  /* one entry per API that needs approval */
+};
+```

.agents/skills/builtin-tool/references/ui/placeholder.md

@@ -0,0 +1,93 @@
+# Placeholder — Skeleton Between Args and Result (optional)
+
+**Lifecycle:** rendered when the args have finished streaming but the executor hasn't returned yet. Disappears when `pluginState` arrives. Bridges the moment of perceived lag.
+
+**Add for** APIs with noticeable execution time: web search, network crawl, file list, large grep. **Skip for** instant ops (status flips, calculator).
+
+## Props (`BuiltinPlaceholderProps<Args>`)
+
+```ts
+interface BuiltinPlaceholderProps<T extends Record<string, any> = any> {
+  apiName: string;
+  args?: T;
+  identifier: string;
+}
+```
+
+No `pluginState` — Placeholder lives entirely in the "executing" gap.
+
+## Canonical example — Search Placeholder
+
+`packages/builtin-tool-web-browsing/src/client/Placeholder/Search.tsx`:
+
+```tsx
+import type { BuiltinPlaceholderProps, SearchQuery } from '@lobechat/types';
+import { Flexbox, Icon, Skeleton } from '@lobehub/ui';
+import { createStaticStyles, cx } from 'antd-style';
+import { SearchIcon } from 'lucide-react';
+import { memo } from 'react';
+
+import { useIsMobile } from '@/hooks/useIsMobile';
+import { shinyTextStyles } from '@/styles';
+
+const styles = createStaticStyles(({ css, cssVar }) => ({
+  query: cx(
+    css`
+      padding: 4px 8px;
+      border-radius: 8px;
+      font-size: 12px;
+      color: ${cssVar.colorTextSecondary};
+      &:hover {
+        background: ${cssVar.colorFillTertiary};
+      }
+    `,
+    shinyTextStyles.shinyText,
+  ),
+}));
+
+export const Search = memo<BuiltinPlaceholderProps<SearchQuery>>(({ args }) => {
+  const { query } = args || {};
+  const isMobile = useIsMobile();
+
+  return (
+    <Flexbox gap={8}>
+      <Flexbox horizontal={!isMobile} gap={isMobile ? 8 : 40}>
+        <Flexbox horizontal align="center" className={styles.query} gap={8}>
+          <Icon icon={SearchIcon} />
+          {query ? query : <Skeleton.Block active style={{ height: 20, width: 40 }} />}
+        </Flexbox>
+        <Skeleton.Block active style={{ height: 20, width: 40 }} />
+      </Flexbox>
+      <Flexbox horizontal gap={12}>
+        {[1, 2, 3, 4, 5].map((id) => (
+          <Skeleton.Button active key={id} style={{ borderRadius: 8, height: 80, width: 160 }} />
+        ))}
+      </Flexbox>
+    </Flexbox>
+  );
+});
+```
+
+## Placeholder rules
+
+- **Mirror the eventual Render's layout.** When the result arrives the Placeholder unmounts and the Render mounts; if they share dimensions, the chat doesn't jump.
+- Use `Skeleton.Block` / `Skeleton.Button` from `@lobehub/ui` for placeholder shapes.
+- Embed any args you have (e.g. the query text) — context helps the user know what's loading.
+- Pulse with `shinyTextStyles.shinyText` if the Placeholder includes literal text.
+
+## Placeholder registry — `client/Placeholder/index.ts`
+
+```ts
+import { WebBrowsingApiName } from '../../types';
+import CrawlMultiPages from './CrawlMultiPages';
+import CrawlSinglePage from './CrawlSinglePage';
+import { Search } from './Search';
+
+export const WebBrowsingPlaceholders = {
+  [WebBrowsingApiName.crawlMultiPages]: CrawlMultiPages,
+  [WebBrowsingApiName.crawlSinglePage]: CrawlSinglePage,
+  [WebBrowsingApiName.search]: Search,
+};
+
+export { CrawlMultiPages, CrawlSinglePage, Search };
+```

.agents/skills/builtin-tool/references/ui/portal.md

@@ -0,0 +1,71 @@
+# Portal — Full-Screen Detail View (optional)
+
+**Lifecycle:** rendered when the user opens the tool message in a side panel or full-screen modal. One Portal per **tool**, not per API — the Portal switches on `apiName` internally.
+
+**Add for** tools whose results deserve a deep-dive view: search results with editable filters, page content with reader mode, code interpreter sessions.
+
+## Props (`BuiltinPortalProps<Args, State>`)
+
+```ts
+interface BuiltinPortalProps<Arguments = Record<string, any>, State = any> {
+  apiName?: string;
+  arguments: Arguments;
+  identifier: string;
+  messageId: string;
+  state: State;
+}
+```
+
+## Canonical example — Web-Browsing Portal
+
+`packages/builtin-tool-web-browsing/src/client/Portal/index.tsx`:
+
+```tsx
+import type { BuiltinPortalProps, CrawlPluginState, SearchQuery } from '@lobechat/types';
+import { memo } from 'react';
+
+import { WebBrowsingApiName } from '../../types';
+import PageContent from './PageContent';
+import PageContents from './PageContents';
+import Search from './Search';
+
+const Portal = memo<BuiltinPortalProps>(({ arguments: args, messageId, state, apiName }) => {
+  switch (apiName) {
+    case WebBrowsingApiName.search:
+      return <Search messageId={messageId} query={args as SearchQuery} response={state} />;
+
+    case WebBrowsingApiName.crawlSinglePage: {
+      const result = (state as CrawlPluginState).results.find((r) => r.originalUrl === args.url);
+      return <PageContent messageId={messageId} result={result} />;
+    }
+
+    case WebBrowsingApiName.crawlMultiPages:
+      return (
+        <PageContents
+          messageId={messageId}
+          results={(state as CrawlPluginState).results}
+          urls={args.urls}
+        />
+      );
+  }
+  return null;
+});
+export default Portal;
+```
+
+## Portal rules
+
+- One Portal per tool — the file is the routing layer, subcomponents implement each API's view.
+- Portals can read the chat store directly to detect "still streaming" and render a Skeleton internally (see `Search/index.tsx:20-46`).
+- Layout assumes more space than the Render — use `Flexbox` with `height={'100%'}` and structure for a side panel viewport.
+
+## Portal registry — `packages/builtin-tools/src/portals.ts`
+
+```ts
+import { WebBrowsingManifest, WebBrowsingPortal } from '@lobechat/builtin-tool-web-browsing/client';
+import { type BuiltinPortal } from '@lobechat/types';
+
+export const BuiltinToolsPortals: Record<string, BuiltinPortal> = {
+  [WebBrowsingManifest.identifier]: WebBrowsingPortal as BuiltinPortal,
+};
+```

.agents/skills/builtin-tool/references/ui/principles.md

@@ -0,0 +1,19 @@
+# Tool Render 设计原则（中文草案）
+
+这些原则用于判断一个 builtin tool 的 Inspector / Render / Placeholder / Streaming / Intervention / Portal 应该做什么，以及做到什么程度。
+
+1. **先保证折叠态可读。** 每个 API 都必须有 Inspector；用户不展开也应该能看懂 “正在做什么 / 对什么做 / 当前结果是什么”。Inspector 不应该只展示函数名和原始参数。
+2. **Inspector 是一句话，不是详情页。** 优先表达动作、关键对象、数量、状态，例如 “分析图片 3 张”“搜索 12 个结果”“读取 config.json”。长文本、列表和结构化结果放到 Render 或 Portal。
+3. **Inspector 要覆盖执行生命周期。** `args` 还在 streaming、工具执行中、执行完成、执行失败时都应该有稳定展示；必要时同时读取 `args`、`partialArgs` 和 `pluginState`，避免出现空白、跳变或只显示半截参数。
+4. **文案要随状态切换时态。** 同一个动作在 loading 与 completed 两个阶段必须用不同的措辞：执行中用现在进行时（“正在创建任务 / Creating task / 正在搜索”），执行完成后切到完成态（“已创建任务 / Task created / 已找到 N 条”）。Inspector chip 会一直留在聊天记录里 —— 如果一直挂着 “正在 xxx”，几小时后回看历史时会读起来像还在跑。约定的 i18n 形式是 `<api>.loading` / `<api>.completed` 一对键（见 `lobe-agent.apiName.callSubAgent.{loading,completed}` 与 `lobe-claude-code.task.{create,list,update,get}.{loading,completed}`），渲染时按 `isArgumentsStreaming || isLoading` 决定取哪一个。只读 / 查询类（“查看任务” 这种本来就是名词性的）可以共用一个键。
+5. **只有结构化结果才需要 Render。** 如果工具结果只是自然语言总结，通常不需要 Render；如果结果包含列表、媒体、文件、表格、代码、diff、地图、时间线、权限请求等结构，就应该提供 Render。
+6. **Render 要帮助用户检查结果，而不是复述参数。** Render 的主体应该围绕工具产物组织：可预览、可比较、可筛选、可定位。参数只作为上下文辅助出现，不要把 Render 做成一块更大的 args dump。
+7. **参数和结果要一起参与渲染。** 好的 Tool UI 通常同时用 `args` 解释意图，用 `pluginState` 展示真实执行结果；但 `pluginState` 只放结果域数据，不要反向塞入可以从 `args` 推导出的内容。
+8. **慢操作要有 Placeholder。** 如果工具通常需要等待网络、文件系统、模型或外部进程，Placeholder 应该先占住最终 Render 的版式，让用户知道即将看到什么，而不是只显示一个泛化 loading。
+9. **Streaming 只用于连续产物。** 搜索列表、日志、长文本、文件分析、分阶段计划适合 Streaming；一次性小结果不需要强行做 Streaming。Streaming UI 要能渐进追加，并且完成后自然过渡到最终 Render。
+10. **有风险的动作必须 Intervention。** 写文件、删除、发送、安装、执行命令、外部可见操作、权限敏感操作，都应该在执行前给出可理解的确认界面；确认文案要说明影响范围，而不是只问 “是否继续”。
+11. **错误、空态和截断都是正式状态。** Render 不能在失败、无结果、超长结果时退化成空白。错误要说明发生在哪一步；空态要告诉用户没有产物；超长内容要明确 “展示前 N 项 / 还有 N 项”。
+12. **信息密度要克制。** 默认展示最有判断价值的部分：标题、来源、状态、摘要、少量关键字段。大对象、长列表、原文、调试数据放进可展开区域或 Portal，避免把聊天流撑成后台管理页。
+13. **视觉上融入聊天流。** Tool UI 应该使用 `@lobehub/ui` / base-ui、`Flexbox`、`createStaticStyles` 和 `cssVar.*`，遵循现有间距、圆角、颜色、字号；不要为单个工具发明一套独立视觉语言。具体的样式约定见 [shared-rules.md](shared-rules.md)。
+14. **Devtools fixture 是验收入口。** 新增或修改 Tool UI 时，应在 `/devtools` 里准备覆盖典型态、loading/streaming、空态、错误态、长内容态的 fixture；一个 API 如果在真实聊天里会出现，就不应该在 devtools 中缺席。
+15. **先做用户会看的 UI，再做调试 UI。** Raw JSON、trace、schema、内部 id 可以存在，但应默认收起或放到调试区；主界面先回答用户最关心的问题：工具做了什么，结果值不值得信任，下一步能做什么。

.agents/skills/builtin-tool/references/ui/render.md

@@ -0,0 +1,101 @@
+# Render — Rich Result Card (optional)
+
+**Lifecycle:** rendered **once the result arrives** (after Placeholder/Streaming hand off). Sits below the Inspector header.
+
+**Skip if** the API is read-only or the result is just text — the framework already shows the executor's `content` string. Add a Render only when there's a structured artifact worth seeing: a card, a chart, a diff, a list of files.
+
+## Props (`BuiltinRenderProps<Args, State, Content>`)
+
+```ts
+interface BuiltinRenderProps<Arguments = any, State = any, Content = any> {
+  apiName?: string;
+  args: Arguments; // final params from the LLM
+  content: Content; // executor's content string (or parsed)
+  identifier?: string;
+  messageId: string; // for store lookups
+  pluginError?: any; // from BuiltinToolResult.error
+  pluginState?: State; // executor's state
+  toolCallId?: string;
+}
+```
+
+## Two patterns
+
+**Pattern A — Single-file Render** (web-browsing CrawlSinglePage):
+
+```tsx
+// client/Render/CrawlSinglePage.tsx
+import type { BuiltinRenderProps, CrawlPluginState, CrawlSinglePageQuery } from '@lobechat/types';
+import { memo } from 'react';
+
+import PageContent from './PageContent';
+
+const CrawlSinglePage = memo<BuiltinRenderProps<CrawlSinglePageQuery, CrawlPluginState>>(
+  ({ messageId, pluginState, args }) => (
+    <PageContent messageId={messageId} results={pluginState?.results} urls={[args?.url]} />
+  ),
+);
+export default CrawlSinglePage;
+```
+
+**Pattern B — Folder with subcomponents** (web-browsing Search):
+
+```
+client/Render/Search/
+├── index.tsx           # composes the subcomponents, handles error states
+├── ConfigForm.tsx      # appears when pluginError.type === 'PluginSettingsInvalid'
+├── SearchQuery.tsx     # editable query header
+└── SearchResult.tsx    # result list
+```
+
+Use Pattern B when the Render has internal state (editing mode, expanded items), error variants, or is large enough to benefit from splitting.
+
+## Error handling in Render
+
+Renders are the canonical place to surface `pluginError` because the chat doesn't auto-render typed errors:
+
+```tsx
+if (pluginError) {
+  if (pluginError?.type === 'PluginSettingsInvalid') {
+    return <ConfigForm id={messageId} provider={pluginError.body?.provider} />;
+  }
+  return (
+    <Alert
+      title={pluginError?.message}
+      type="error"
+      extra={<Highlighter language="json">{JSON.stringify(pluginError.body, null, 2)}</Highlighter>}
+    />
+  );
+}
+```
+
+## Render rules
+
+- **Return `null`** if there's nothing useful to draw yet (avoids empty cards during stream).
+- Use `pluginState` for server-truth (ids, counts, server-assigned status) and `args` for what the LLM asked. **Combine — neither alone is enough.**
+- For lists, summarize with a header line and show top N items with a "+N more" tail rather than rendering everything.
+- **Keep the Render single-layer** — the tool card is already your surface, so don't open with your own filled container and then nest more filled boxes inside it. See [shared-rules.md](shared-rules.md) → "Stay single-layer".
+- For modals from a Render, use `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
+
+## Render registry — `client/Render/index.ts`
+
+```ts
+import type { BuiltinRender } from '@lobechat/types';
+
+import { TaskApiName } from '../../types';
+import CreateTaskRender from './CreateTask';
+import RunTasksRender from './RunTasks';
+
+export const TaskRenders: Record<string, BuiltinRender> = {
+  [TaskApiName.createTask]: CreateTaskRender as BuiltinRender,
+  [TaskApiName.runTasks]: RunTasksRender as BuiltinRender,
+  /* only the APIs with rich result UI — others fall back to text content */
+};
+
+export { default as CreateTaskRender } from './CreateTask';
+export { default as RunTasksRender } from './RunTasks';
+```
+
+## Render display control (rare)
+
+If the Render should hide for certain results (e.g. ClaudeCode's TodoWrite hides when the agent is mid-stream), add a `RenderDisplayControl` to `packages/builtin-tools/src/displayControls.ts`. See `ClaudeCodeRenderDisplayControls` for the pattern.

.agents/skills/builtin-tool/references/ui/shared-rules.md

@@ -0,0 +1,89 @@
+# Shared Style Rules
+
+These apply across every surface.
+
+## The component skeleton
+
+Every surface file is the same shape, so internalize it once instead of re-deriving it per rule. The skeleton below bakes in five mechanical conventions — copy it and fill the body:
+
+```tsx
+'use client'; // (a) leaves of the chat tree must not block server rendering
+
+import type { BuiltinInspectorProps, SearchQuery, UniformSearchResponse } from '@lobechat/types';
+import { memo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+// (b) type with BuiltinXProps<Args, State> — never widen to `any`.
+//     Args = the JSON Schema params, State = the executor's `state` field;
+//     they should match <Name>Params / <Name>State from types.ts.
+export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
+  ({ args, pluginState }) => {
+    const { t } = useTranslation('plugin'); // (c) all strings from the `plugin` namespace
+
+    // (d) cross-cutting state (loading, streaming buffer) comes from the store,
+    //     not props — props only carry args/state/messageId.
+    // const buffer = useChatStore((s) => chatToolSelectors.streamingBuffer(messageId)(s));
+
+    return <span>{t('builtins.<identifier>.apiName.search')}</span>;
+  },
+);
+SearchInspector.displayName = 'SearchInspector'; // (e) always memo + displayName
+export default SearchInspector;
+```
+
+- **(c)** Default an Inspector to `t('builtins.<identifier>.apiName.<api>')` so the row is non-empty while args stream in.
+- **(d)** Read the store via Zustand selectors inside the component; see [streaming.md](streaming.md) for the buffer selector.
+
+## Styling: `createStaticStyles + cssVar.*`, `@lobehub/ui` over `antd`
+
+Zero-runtime CSS-in-JS — styles compile once and read CSS variables at runtime:
+
+```tsx
+import { createStaticStyles, cssVar } from 'antd-style';
+
+const styles = createStaticStyles(({ css, cssVar }) => ({
+  chip: css`
+    padding-block: 2px;
+    padding-inline: 8px;
+    border-radius: 999px;
+    color: ${cssVar.colorText};
+    background: ${cssVar.colorFillTertiary};
+  `,
+}));
+```
+
+- Fall back to `createStyles + token` only when you need runtime token computation (rare). Inline `style={{ color: cssVar.colorTextSecondary }}` is fine for one-off dynamic values.
+- Components come from `@lobehub/ui` (`Block`, `Text`, `Flexbox`, `Highlighter`, `Alert`, `Tooltip`, `Skeleton`), not raw `antd`. Modals come from `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
+- Note: `<Text type='secondary'>` is a lighter shade than `colorTextSecondary`. For that exact token color, write `<Text style={{ color: cssVar.colorTextSecondary }}>`.
+
+## Stay single-layer — don't nest filled cards
+
+The framework already wraps every Render / Intervention in a tool card, so that card **is** your surface. A Render that opens with its own `background: ${cssVar.colorFillQuaternary}` container is already one card deep; put another filled box inside it (`colorBgContainer` / `colorFillTertiary`) and you get the card-in-card look that reads as "complex" — two or three stacked fills for what is really a flat list of fields.
+
+- **The outermost wrapper carries no fill.** Use a flat container with only `padding-block: 4px` for breathing room; let the tool card provide the card. (See `Agent/index.tsx`'s `container`.)
+- **At most one filled box, and only to delineate real content** — a Markdown preview, a diff, a code/result block. Labels, key–value fields, question/answer text, chips: render flat on the surface, separated by spacing or a hairline divider (`height: 1px; background: ${cssVar.colorFillSecondary}`), not by wrapping each in its own box.
+- **A box on a flat surface needs a visible fill.** Once the outer fill is gone, an inner `colorBgContainer` box can vanish against the tool card (same color). Use `colorFillTertiary` for the one content box so it still reads as delineated.
+- Don't wrap a single value in a box just to give it padding — that's the redundant-nesting smell (a `detailCard` around a `value` box around one string).
+
+```tsx
+// ❌ card-in-card: filled container wrapping a filled preview box
+container: css`
+  padding: 12px;
+  background: ${cssVar.colorFillQuaternary};
+`,
+previewBox: css`
+  background: ${cssVar.colorBgContainer};
+`,
+
+// ✅ single-layer: flat container, one visible content box
+container: css`
+  padding-block: 4px;
+`,
+previewBox: css`
+  background: ${cssVar.colorFillTertiary};
+`,
+```
+
+For the common "icon + file/title header, then one content box" shape, reuse `ToolResultCard` from `@lobechat/shared-tool-ui/components` instead of rebuilding it — it's already single-layer (flat wrapper, one `colorFillTertiary` content box) and is what CC `Read` / `Grep` / `Glob` / `Write` / `WebSearch` / `WebFetch` render through.
+
+The exception is a deliberate **panel** pattern — an `<Block variant="outlined">` with a header bar + list rows (CC `TodoWrite` / `Task`). There the single outlined block is the panel and the header fill is a header bar, not a nested card. One structured panel is fine; stacked decorative fills are not.

.agents/skills/builtin-tool/references/ui/streaming.md

@@ -0,0 +1,83 @@
+# Streaming — Live Output During Execution (optional)
+
+**Lifecycle:** rendered **while the executor is still running** for APIs that emit incremental output. The component is responsible for fetching the in-flight stream from the chat store and rendering it.
+
+**Add for** long-running ops with continuous output: shell command execution (stdout/stderr), file write progress, code interpreter cells.
+
+## Props (`BuiltinStreamingProps<Args>`)
+
+```ts
+interface BuiltinStreamingProps<Arguments = any> {
+  apiName: string;
+  args: Arguments;
+  identifier: string;
+  messageId: string; // use to fetch the streaming buffer from store
+  toolCallId: string;
+}
+```
+
+Note there's **no `state` or `result` prop** — the Streaming component is for the in-flight phase. It pulls the live buffer from the store itself (typically via `chatToolSelectors.streamingContent(messageId)` or similar).
+
+## Canonical example — RunCommandStreaming
+
+`packages/builtin-tool-local-system/src/client/Streaming/RunCommand/index.tsx`:
+
+```tsx
+'use client';
+
+import type { BuiltinStreamingProps } from '@lobechat/types';
+import { Highlighter } from '@lobehub/ui';
+import { memo } from 'react';
+
+interface RunCommandParams {
+  command?: string;
+  description?: string;
+  timeout?: number;
+}
+
+export const RunCommandStreaming = memo<BuiltinStreamingProps<RunCommandParams>>(({ args }) => {
+  const { command } = args || {};
+  if (!command) return null;
+
+  return (
+    <Highlighter
+      animated
+      wrap
+      language="sh"
+      showLanguage={false}
+      style={{ padding: '4px 8px' }}
+      variant="outlined"
+    >
+      {command}
+    </Highlighter>
+  );
+});
+RunCommandStreaming.displayName = 'RunCommandStreaming';
+```
+
+For real-time output beyond just the command (stderr/stdout streaming), pull from the chat store:
+
+```tsx
+const buffer = useChatStore((state) =>
+  chatToolSelectors.streamingBuffer(messageId, toolCallId)(state),
+);
+```
+
+## Streaming rules
+
+- Render `null` until you have something to display (avoids flash).
+- For terminal-style output, use `Highlighter` with `animated` to show typing-like effect.
+- The Streaming component must **unmount cleanly** when execution ends — typically the framework swaps it out for the Render automatically.
+
+## Streaming registry — `client/Streaming/index.ts`
+
+```ts
+import { LocalSystemApiName } from '../..';
+import { RunCommandStreaming } from './RunCommand';
+import { WriteFileStreaming } from './WriteFile';
+
+export const LocalSystemStreamings = {
+  [LocalSystemApiName.runCommand]: RunCommandStreaming,
+  [LocalSystemApiName.writeLocalFile]: WriteFileStreaming,
+};
+```

.agents/skills/chat-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chat-sdk
-description: "Build multi-platform chat bots with the Chat SDK (`chat` npm package) — Slack, Teams, Google Chat, Discord, GitHub, Linear. Use when building a chat bot, handling mentions / messages / reactions / slash commands / cards / modals / streaming, setting up a webhook handler, or sending interactive cards / streaming AI responses to a chat platform. Triggers on `@chat-adapter`, 'chat sdk', 'chat bot', 'slack bot', 'teams bot', 'discord bot', 'webhook handler', 'cross-platform bot'."
+description: 'Build multi-platform chat bots with the chat SDK. Use for Slack, Teams, Google Chat, Discord, GitHub, Linear bots, webhooks, mentions, slash commands, cards, modals, or streaming responses.'
 user-invocable: false
 ---
 

.agents/skills/cli-backend-testing/SKILL.md

@@ -29,10 +29,9 @@ Standard workflow for verifying backend changes using the LobeHub CLI (`lh`) aga
 
 ## Quick Reference
 
-All CLI dev commands run from `lobehub/apps/cli/`:
+All CLI dev commands run from `lobehub/apps/cli/`. Subsequent examples use `$CLI`:
 
 ```bash
-# Shorthand for all commands below
 CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"
 ```
 
@@ -40,17 +39,14 @@ CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"
 
 ### Step 1: Ensure Dev Server is Running
 
-Check if the dev server is already running:
-
 ```bash
 curl -s -o /dev/null -w '%{http_code}' http://localhost:3011/ 2> /dev/null
 ```
 
-- **If reachable** (returns any HTTP status): server is running. Skip to Step 2.
-- **If unreachable**: start the server:
+- **If reachable**: skip to Step 2.
+- **If unreachable**: start from cloud repo root:
 
 ```bash
-# From cloud repo root
 pnpm run dev:next
 ```
 
@@ -65,37 +61,33 @@ pnpm run dev:next
 
 ### Step 2: Check CLI Authentication
 
-Check if dev credentials already exist:
-
 ```bash
 cat lobehub/apps/cli/.lobehub-dev/settings.json 2> /dev/null
 ```
 
-- **If file exists and contains `"serverUrl": "http://localhost:3011"`**: already authenticated. Skip to Step 3.
-- **If file missing or points to wrong server**: login is needed. Ask the user to run:
+- **If file exists and contains `"serverUrl": "http://localhost:3011"`**: skip to Step 3.
+- **If missing or wrong server**: ask the user to run:
 
 ```bash
 ! cd lobehub/apps/cli && LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts login --server http://localhost:3011
 ```
 
-> Login requires interactive browser authorization (OIDC Device Code Flow), so the user must run it themselves via `!` prefix. After login, credentials are saved to `lobehub/apps/cli/.lobehub-dev/` and persist across sessions.
+> Login requires interactive browser authorization (OIDC Device Code Flow), so the user must run it themselves via `!` prefix. Credentials persist in `lobehub/apps/cli/.lobehub-dev/`.
 
 ### Step 3: Test with CLI Commands
 
-CLI runs from source (`bun src/index.ts`), so CLI-side code changes take effect immediately without rebuilding.
+CLI runs from source, so CLI-side code changes take effect immediately without rebuilding.
 
 ```bash
 cd lobehub/apps/cli
-LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
+$CLI <command>
 ```
 
 ### Step 4: Clean Up Test Data
 
-Delete any test data created during verification:
-
 ```bash
-LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts task delete < id > -y
-LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts agent delete < id > -y
+$CLI task delete < id > -y
+$CLI agent delete < id > -y
 ```
 
 ## Common Testing Patterns
@@ -103,51 +95,30 @@ LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts agent delete < id > -y
 ### Task System
 
 ```bash
-# List tasks
 $CLI task list
-
-# Create test data with nesting
 $CLI task create -n "Root Task" -i "Test instruction"
 $CLI task create -n "Child Task" -i "Sub instruction" --parent T-1
-
-# View task detail (tests getTaskDetail service)
 $CLI task view T-1
-
-# View task tree
 $CLI task tree T-1
-
-# Test lifecycle
 $CLI task edit T-1 --status running
 $CLI task comment T-1 -m "Test comment"
-
-# Clean up
 $CLI task delete T-1 -y
 ```
 
 ### Agent System
 
 ```bash
-# List agents
 $CLI agent list
-
-# View agent detail
 $CLI agent view <agent-id>
-
-# Run agent (tests agent execution pipeline)
 $CLI agent run <agent-id> -m "Test prompt"
 ```
 
 ### Document & Knowledge Base
 
 ```bash
-# List documents
 $CLI doc list
-
-# Create and view
 $CLI doc create -t "Test Doc" -c "Content here"
 $CLI doc view <doc-id>
-
-# Knowledge base
 $CLI kb list
 $CLI kb tree <kb-id>
 ```
@@ -155,18 +126,13 @@ $CLI kb tree <kb-id>
 ### Model & Provider
 
 ```bash
-# List models and providers
 $CLI model list
 $CLI provider list
-
-# Test provider connectivity
 $CLI provider test <provider-id>
 ```
 
 ## Dev-Test Cycle
 
-The standard cycle for backend development:
-
 ```
 1. Make code changes (service/model/router/type)
          |
@@ -177,7 +143,7 @@ The standard cycle for backend development:
    lsof -ti:3011 | xargs kill && pnpm run dev:next
          |
 4. CLI verification (end-to-end)
-   LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
+   $CLI <command>
          |
 5. Clean up test data
 ```
@@ -193,10 +159,6 @@ The standard cycle for backend development:
 | `lobehub/apps/cli/` (CLI code)            | No       |
 | `src/` (cloud overrides)                  | Yes      |
 
-### When Server Restart is NOT Needed
-
-CLI runs from source via `bun src/index.ts`, so any changes to `lobehub/apps/cli/src/` take effect immediately on next command invocation.
-
 ## Troubleshooting
 
 | Issue                       | Solution                                                              |
@@ -207,12 +169,3 @@ CLI runs from source via `bun src/index.ts`, so any changes to `lobehub/apps/cli
 | CLI shows old data/behavior | Server needs restart to pick up code changes                          |
 | `EADDRINUSE` on port 3011   | Server already running; kill with `lsof -ti:3011 \| xargs kill`       |
 | Login opens wrong server    | Must use `--server http://localhost:3011` flag (env var doesn't work) |
-
-## Credential Isolation
-
-| Mode       | Credential Dir                   | Server            |
-| ---------- | -------------------------------- | ----------------- |
-| Dev        | `lobehub/apps/cli/.lobehub-dev/` | `localhost:3011`  |
-| Production | `~/.lobehub/`                    | `app.lobehub.com` |
-
-The two environments are completely isolated. Dev mode credentials are gitignored.

.agents/skills/data-fetching-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: data-fetching-architecture
-description: Standardized data-fetching pipeline guide — Service layer + Zustand Store + SWR. Use when implementing a data-fetching feature, creating a `xxxService`, adding a `useFetchXxx` hook, wiring `useClientDataSWR`, or migrating ad-hoc `useEffect + fetch` to the standard pipeline. Triggers on `lambdaClient`, `useClientDataSWR`, `xxxService`, `useFetchXxx`, 'data fetching', 'fetch architecture', 'service layer', 'SWR hook', 'migrate useEffect'.
+description: 'LobeHub data-fetching pipeline guide. Use for service layer, Zustand store, SWR, lambdaClient, useClientDataSWR, useFetchXxx hooks, or migrating useEffect fetches.'
 user-invocable: false
 ---
 

.agents/skills/db-migrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: db-migrations
-description: 'Use when generating or regenerating Drizzle migration files, changing database schema tables or columns, resolving migration sequence conflicts after rebase, reviewing migration SQL for idempotent patterns, or renaming migration files.'
+description: 'Use for Drizzle migrations: schema/table/column changes, migration generation or regeneration, sequence conflicts after rebase, idempotent SQL review, or migration renames.'
 user-invocable: false
 ---
 

.agents/skills/debug-package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-package
-description: "Guide for the `debug` npm package and LobeHub log namespaces (lobe-server:*, lobe-desktop:*, lobe-client:*, lobe-*-router:*). Use whenever adding a `debug(...)` logger, picking a namespace for new server/desktop/client/router code, troubleshooting why DEBUG=lobe-* logs don't show up, or when the user asks to 'add logging', 'add a logger', 'instrument this', 'trace this call', 'why isn't my log printing', or mentions `debug(`, `DEBUG=`, `localStorage.debug`, or log format specifiers like %O / %o / %s / %d in a LobeHub codebase."
+description: 'LobeHub debug package and log namespace guide. Use when adding debug() logging, choosing lobe-* namespaces, troubleshooting DEBUG output, localStorage.debug, or log format specifiers.'
 user-invocable: false
 ---
 

.agents/skills/docs-changelog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-changelog
-description: "Writing guide for website changelog pages under `docs/changelog/*.mdx` (NOT GitHub Release notes — those live in the `version-release` skill). Use when creating or editing a product update post in EN/ZH. Triggers on `docs/changelog/*.mdx`, 'changelog post', 'product update post', 'add a changelog', '更新日志', 'changelog 文案'."
+description: 'Write website changelog pages under docs/changelog/*.mdx. Use for EN/ZH product update posts, changelog posts, update-log copy, or docs changelog edits; not GitHub Release notes.'
 ---
 
 # Docs Changelog Writing Guide

.agents/skills/drizzle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: drizzle
-description: "Drizzle ORM schema authoring and query style for LobeHub (postgres, strict mode). Use when editing anything under `src/database/schemas/`, defining `pgTable` columns/indexes/junction tables, spreading `...timestamps`, generating `createInsertSchema`/`$inferSelect`/`$inferInsert` types, writing `db.select().from(...).leftJoin(...)` queries, or deciding when to split a relational `with:` into two queries. Triggers on `pgTable`, `db.select`, `db.query`, `eq()`/`and()`/`inArray()`, `uniqueIndex`, `primaryKey`, `references({ onDelete })`, 'add a column', 'new table', 'foreign key', 'junction table', 'schema field'. For migration files specifically, see the `db-migrations` skill."
+description: 'LobeHub Drizzle ORM schema and query style. Use for pgTable schemas, indexes, joins, inferred types, db.select/db.query, schema fields, foreign keys, junction tables, or postgres query patterns.'
 user-invocable: false
 ---
 
@@ -9,13 +9,13 @@ user-invocable: false
 ## Configuration
 
 - Config: `drizzle.config.ts`
-- Schemas: `src/database/schemas/`
-- Migrations: `src/database/migrations/`
+- Schemas: `packages/database/src/schemas/`
+- Migrations: `packages/database/migrations/`
 - Dialect: `postgresql` with `strict: true`
 
 ## Helper Functions
 
-Location: `src/database/schemas/_helpers.ts`
+Location: `packages/database/src/schemas/_helpers.ts`
 
 - `timestamptz(name)`: Timestamp with timezone
 - `createdAt()`, `updatedAt()`, `accessedAt()`: Standard timestamp columns
@@ -174,6 +174,94 @@ const rows = await this.db
   .groupBy(agentEvalDatasets.id);
 ```
 
+### Raw SQL and Advanced Queries
+
+Prefer Drizzle builders whenever the query can be expressed clearly with `select`,
+`insert().select()`, `update().from()`, joins, CTEs, `groupBy`, and typed selected
+columns. This keeps table and column references tied to schema definitions, so
+schema changes are more likely to surface as TypeScript errors.
+
+Expression-level `sql<T>` is fine inside a Drizzle builder for PostgreSQL features
+that do not have a dedicated helper, such as JSON path extraction, casts, aggregate
+expressions, `CASE`, `NOW()`, or advisory locks. Row locks are query clauses, not
+expressions; use the select builder's `.for('update')` instead of raw
+`FOR UPDATE` SQL fragments.
+
+When refactoring raw SQL:
+
+- Preserve the original query shape for latency-sensitive paths. If raw SQL is one
+  database roundtrip, do not replace it with multiple depth-based queries just to
+  remove `execute`.
+- Use `$with(...)` plus `insert().select()` / `update().from()` for multi-step
+  single-roundtrip writes when Drizzle can express the data flow.
+- Avoid generic `execute<MyRow>(sql...)` as the main safety mechanism. It types the
+  returned rows, but it does not keep selected columns in sync with schema changes.
+- If the only clean implementation is a PostgreSQL feature that Drizzle cannot
+  express well, keep the raw SQL and tighten it instead: use schema references in
+  interpolations, explicit user scope, a narrow row interface, and regression tests.
+
+Recursive CTEs are a special case: current Drizzle usage in this repo does not have
+a clean `WITH RECURSIVE` builder pattern. Keep recursive CTE raw SQL when replacing
+it would add extra database roundtrips or materially worsen performance.
+
+Example: convert an aggregate query when Drizzle can preserve one roundtrip:
+
+```typescript
+// ✅ Good: builder owns table and column references; sql<T> stays expression-level.
+const rows = await trx
+  .select({
+    model: messages.model,
+    provider: messages.provider,
+    totalCost: sql<string | null>`sum((${messages.metadata}->'usage'->>'cost')::numeric)`.as(
+      'totalCost',
+    ),
+  })
+  .from(messages)
+  .where(
+    and(
+      eq(messages.topicId, topicId),
+      eq(messages.userId, userId),
+      eq(messages.role, 'assistant'),
+      sql`${messages.metadata} ? 'usage'`,
+    ),
+  )
+  .groupBy(messages.provider, messages.model);
+```
+
+Example: use the select lock builder for row locks:
+
+```typescript
+const [user] = await trx.select().from(users).where(eq(users.id, userId)).for('update');
+```
+
+Example: keep a recursive CTE raw when replacing it would add depth-based DB
+roundtrips:
+
+```typescript
+interface TaskTreeRow {
+  id: string;
+  parent_task_id: string | null;
+}
+
+// execute<T> is acceptable here only because Drizzle has no clean WITH RECURSIVE
+// builder; a builder rewrite would add depth-based roundtrips. Keep schema refs in
+// the interpolations and scope every leg to the user.
+const { rows } = await db.execute<TaskTreeRow>(sql`
+  WITH RECURSIVE task_tree AS (
+    SELECT ${tasks.id}, ${tasks.parentTaskId}
+    FROM ${tasks}
+    WHERE ${tasks.id} = ${rootTaskId}
+      AND ${tasks.createdByUserId} = ${userId}
+    UNION ALL
+    SELECT ${tasks.id}, ${tasks.parentTaskId}
+    FROM ${tasks}
+    JOIN task_tree ON ${tasks.parentTaskId} = task_tree.id
+    WHERE ${tasks.createdByUserId} = ${userId}
+  )
+  SELECT * FROM task_tree
+`);
+```
+
 ### One-to-Many (Separate Queries)
 
 When you need a parent record with its children, use two queries instead of relational `with:`:

.agents/skills/heterogeneous-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: heterogeneous-agent
-description: Guide for implementing and debugging LobeHub heterogeneous agent integrations such as Claude Code, Codex, and future external CLI agents. Use when working on adapter event mapping, Electron IPC transport, renderer persistence, tool-call chaining, subagent threads, resume/session handling, or regressions like mixed multi-tool messages, broken step boundaries, stuck tool loading, and orphan tool messages. Triggers on 'heterogeneous agent', 'hetero agent', '异构 agent', 'claude code adapter', 'codex adapter', 'external agent CLI', '孤立 tool 消息', 'raw Codex trace', or adapter/executor bugs.
+description: 'Implement or debug LobeHub heterogeneous agents. Use for Claude Code/Codex adapters, external CLI agents, event mapping, IPC, persistence, tool-call chains, sessions, traces, or adapter bugs.'
 ---
 
 # Heterogeneous Agent Development

.agents/skills/hotkey/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hotkey
-description: "Adding or editing keyboard shortcuts in LobeHub. Use when registering a new hotkey, changing a key combo, scoping a shortcut to chat vs global, or wiring a hotkey hook + tooltip. Covers the 5-step flow: add to `HotkeyEnum` in `src/types/hotkey.ts`, register in `HOTKEYS_REGISTRATION` (`src/const/hotkeys.ts`) with `combineKeys([Key.Mod, …])`, add i18n in `src/locales/default/hotkey.ts`, expose via `useHotkeyById` in `src/hooks/useHotkeys/`, and render `<Tooltip hotkey={…}>`. Triggers on `HotkeyEnum`, `HOTKEYS_REGISTRATION`, `useHotkeyById`, `combineKeys`, `Key.Mod`/`Key.Shift`, 'add a hotkey', 'add a shortcut', '加快捷键', '快捷键', 'Cmd+K', 'keyboard shortcut', 'hotkey scope', 'hotkey conflict'."
+description: 'Add or edit LobeHub keyboard shortcuts. Use for HotkeyEnum, HOTKEYS_REGISTRATION, combineKeys, useHotkeyById, tooltip hotkeys, shortcut scope, conflicts, or Cmd/Ctrl key combos.'
 user-invocable: false
 ---
 

.agents/skills/i18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: i18n
-description: "LobeHub internationalization with react-i18next. Use when adding any user-facing string in `.tsx`/`.ts` files, creating or renaming a key under `src/locales/default/{namespace}.ts`, deciding the `{feature}.{context}.{action}` flat-key pattern, wiring a new namespace into `src/locales/default/index.ts`, or translating zh-CN/en-US JSON for dev preview. Triggers on `useTranslation`, `t('foo.bar')`, `i18next.t`, `{{variable}}` interpolation, hardcoded UI strings (zh or en) that should be extracted, 'add i18n', '加 i18n key', '翻译', 'locale key', 'namespace', 'pnpm i18n'."
+description: 'LobeHub i18n with react-i18next. Use for user-facing strings, locale keys, namespaces, useTranslation, t(), interpolation, zh-CN/en-US previews, hardcoded UI copy, or pnpm i18n.'
 user-invocable: false
 ---
 

.agents/skills/linear/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: linear
-description: "Linear issue management. Use when the user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), says 'linear' / 'linear issue' / 'link linear', or when creating PRs that reference Linear issues. Covers retrieving issues, updating status, adding completion comments, and creating sub-issue trees."
+description: 'Linear issue management. Use for LOBE-xxx issues, Linear links, PRs referencing Linear, retrieving issues, updating status, completion comments, or sub-issue trees.'
 user-invocable: false
 ---
 

.agents/skills/local-testing/SKILL.md

@@ -397,35 +397,60 @@ The pattern is the same for every platform:
 
 Pick the file for your target platform — each contains activation, navigation, send-message, and verification snippets specific to that app:
 
-| Platform      | Reference                                          | Quick switcher |
-| ------------- | -------------------------------------------------- | -------------- |
-| Discord       | [references/discord.md](./references/discord.md)   | `Cmd+K`        |
-| Slack         | [references/slack.md](./references/slack.md)       | `Cmd+K`        |
-| Telegram      | [references/telegram.md](./references/telegram.md) | `Cmd+F`        |
-| WeChat / 微信 | [references/wechat.md](./references/wechat.md)     | `Cmd+F`        |
-| Lark / 飞书   | [references/lark.md](./references/lark.md)         | `Cmd+K`        |
-| QQ            | [references/qq.md](./references/qq.md)             | `Cmd+F`        |
+Each channel has its own folder under `bot/<channel>/` containing an `index.md`
+(activation, navigation, send-message, and verification snippets specific to
+that app) and its test script:
 
-For **shared osascript patterns** (activate, type, paste, screenshot, read accessibility, common workflow template, gotchas), see [references/osascript-common.md](./references/osascript-common.md). Read this first if you're new to osascript automation.
+| Platform      | Reference                                        | Quick switcher |
+| ------------- | ------------------------------------------------ | -------------- |
+| Discord       | [bot/discord/index.md](./bot/discord/index.md)   | `Cmd+K`        |
+| Slack         | [bot/slack/index.md](./bot/slack/index.md)       | `Cmd+K`        |
+| Telegram      | [bot/telegram/index.md](./bot/telegram/index.md) | `Cmd+F`        |
+| WeChat / 微信 | [bot/wechat/index.md](./bot/wechat/index.md)     | `Cmd+F`        |
+| Lark / 飞书   | [bot/lark/index.md](./bot/lark/index.md)         | `Cmd+K`        |
+| QQ            | [bot/qq/index.md](./bot/qq/index.md)             | `Cmd+F`        |
+
+For **shared osascript patterns** (activate, type, paste, screenshot, read accessibility, common workflow template, gotchas), see [bot/osascript-common.md](./bot/osascript-common.md). Read this first if you're new to osascript automation.
+
+## Bridge-based channels (no native app)
+
+Some channels have no native app to drive with osascript — they connect through
+a local bridge inside the Desktop app. These are tested with agent-browser
+(IPC + UI) plus the bridge's own HTTP/REST endpoints, not osascript:
+
+| Channel  | Reference                                        | What it drives                                           |
+| -------- | ------------------------------------------------ | -------------------------------------------------------- |
+| iMessage | [bot/imessage/index.md](./bot/imessage/index.md) | `imessageBridge.*` IPC + local bridge + BlueBubbles REST |
+
+For iMessage there is a one-shot regression script — see `test-imessage-bridge.sh` below.
 
 ---
 
 # Scripts
 
-Ready-to-use scripts in `.agents/skills/local-testing/scripts/`:
+**App / recording scripts** in `.agents/skills/local-testing/scripts/`:
 
 | Script                    | Usage                                               |
 | ------------------------- | --------------------------------------------------- |
 | `electron-dev.sh`         | Manage Electron dev env (start/stop/status/restart) |
-| `capture-app-window.sh`   | Capture screenshot of a specific app window         |
 | `record-electron-demo.sh` | Record Electron app demo with ffmpeg                |
 | `record-app-screen.sh`    | Record app screen (video + screenshots, start/stop) |
-| `test-discord-bot.sh`     | Send message to Discord bot via osascript           |
-| `test-slack-bot.sh`       | Send message to Slack bot via osascript             |
-| `test-telegram-bot.sh`    | Send message to Telegram bot via osascript          |
-| `test-wechat-bot.sh`      | Send message to WeChat bot via osascript            |
-| `test-lark-bot.sh`        | Send message to Lark / 飞书 bot via osascript       |
-| `test-qq-bot.sh`          | Send message to QQ bot via osascript                |
+
+**Bot scripts** live under `.agents/skills/local-testing/bot/`, one folder per
+channel (alongside that channel's `index.md`). The shared
+`capture-app-window.sh` sits at the `bot/` root:
+
+| Script                             | Usage                                                               |
+| ---------------------------------- | ------------------------------------------------------------------- |
+| `capture-app-window.sh`            | Capture screenshot of a specific app window (used by bot tests)     |
+| `discord/test-discord-bot.sh`      | Send message to Discord bot via osascript                           |
+| `slack/test-slack-bot.sh`          | Send message to Slack bot via osascript                             |
+| `telegram/test-telegram-bot.sh`    | Send message to Telegram bot via osascript                          |
+| `wechat/test-wechat-bot.sh`        | Send message to WeChat bot via osascript                            |
+| `lark/test-lark-bot.sh`            | Send message to Lark / 飞书 bot via osascript                       |
+| `qq/test-qq-bot.sh`                | Send message to QQ bot via osascript                                |
+| `imessage/test-imessage-bridge.sh` | Regression-test the iMessage BlueBubbles bridge (IPC + HTTP)        |
+| `imessage/send-imessage-test.sh`   | Send one real iMessage (desktop → BB → iMessage) and verify it sent |
 
 ### Window Screenshot Utility
 
@@ -433,9 +458,9 @@ Ready-to-use scripts in `.agents/skills/local-testing/scripts/`:
 
 ```bash
 # Standalone usage
-./.agents/skills/local-testing/scripts/capture-app-window.sh "Discord" /tmp/discord.png
-./.agents/skills/local-testing/scripts/capture-app-window.sh "Slack" /tmp/slack.png
-./.agents/skills/local-testing/scripts/capture-app-window.sh "WeChat" /tmp/wechat.png
+./.agents/skills/local-testing/bot/capture-app-window.sh "Discord" /tmp/discord.png
+./.agents/skills/local-testing/bot/capture-app-window.sh "Slack" /tmp/slack.png
+./.agents/skills/local-testing/bot/capture-app-window.sh "WeChat" /tmp/wechat.png
 ```
 
 All bot test scripts use this utility automatically for their screenshots.
@@ -452,32 +477,48 @@ Examples:
 
 ```bash
 # Discord — test a bot in #bot-testing channel
-./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "!ping"
-./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
+./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "!ping"
+./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
 
 # Slack — test a bot in #bot-testing channel
-./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "@mybot hello"
-./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
+./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "@mybot hello"
+./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
 
 # Telegram — test a bot by username
-./.agents/skills/local-testing/scripts/test-telegram-bot.sh "MyTestBot" "/start"
-./.agents/skills/local-testing/scripts/test-telegram-bot.sh "GPTBot" "Hello" 60
+./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "MyTestBot" "/start"
+./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "GPTBot" "Hello" 60
 
 # WeChat — test a bot or send to a contact
-./.agents/skills/local-testing/scripts/test-wechat-bot.sh "文件传输助手" "test message" 5
-./.agents/skills/local-testing/scripts/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
+./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "文件传输助手" "test message" 5
+./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
 
 # Lark/飞书 — test a bot in a group chat
-./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "@MyBot hello"
-./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "Help me with this" 30
+./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "@MyBot hello"
+./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "Help me with this" 30
 
 # QQ — test a bot in a group or direct chat
-./.agents/skills/local-testing/scripts/test-qq-bot.sh "bot-testing" "Hello bot" 15
-./.agents/skills/local-testing/scripts/test-qq-bot.sh "MyBot" "/help" 10
+./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "bot-testing" "Hello bot" 15
+./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "MyBot" "/help" 10
 ```
 
 Each script: activates the app, navigates to the channel/contact, pastes the message via clipboard, sends, waits, and takes a screenshot. Use the `Read` tool on the screenshot for visual verification.
 
+### iMessage bridge regression script
+
+`test-imessage-bridge.sh` does **not** follow the osascript bot interface — it
+drives the Desktop bridge's IPC + HTTP layers and asserts the result, then
+self-cleans. Needs BlueBubbles running and Electron up with CDP.
+
+```bash
+./.agents/skills/local-testing/bot/imessage/test-imessage-bridge.sh '<bluebubbles_password>' [bb_url] [cdp_port]
+# defaults: bb_url=http://127.0.0.1:1234  cdp_port=9222 — exit 0 = all green
+```
+
+It guards the connect/configure flow (testConfig happy + reject paths, first-time
+`upsertConfig` save, bridge running + webhook registered, local-server secret
+enforcement). See [bot/imessage/index.md](./bot/imessage/index.md)
+for the full manual UI flow and known bugs.
+
 ---
 
 # Screen Recording
@@ -517,4 +558,4 @@ Outputs to `.records/` directory (gitignored): `<name>.mp4` (video) + `<name>/`
 
 ### osascript
 
-See [references/osascript-common.md](./references/osascript-common.md#gotchas) for the full osascript gotchas list (accessibility permissions, `keystroke` non-ASCII issues, locale-specific app names, rate limiting, etc.).
+See [bot/osascript-common.md](./bot/osascript-common.md#gotchas) for the full osascript gotchas list (accessibility permissions, `keystroke` non-ASCII issues, locale-specific app names, rate limiting, etc.).

.agents/skills/local-testing/bot/discord/index.md

@@ -2,7 +2,7 @@
 
 **App name:** `Discord` | **Process name:** `Discord`
 
-See [osascript-common.md](./osascript-common.md) for shared patterns.
+See [osascript-common.md](../osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -92,6 +92,6 @@ echo "Screenshot saved to /tmp/discord-test-result.png"
 ## Script
 
 ```bash
-./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "!ping"
-./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
+./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "!ping"
+./.agents/skills/local-testing/bot/discord/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
 ```

.agents/skills/local-testing/bot/discord/test-discord-bot.sh

@@ -60,5 +60,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/bot/imessage/index.md

@@ -0,0 +1,232 @@
+# iMessage Desktop bridge regression test
+
+The iMessage channel is different from the other bot platforms: there is **no
+native app to drive with osascript**. Instead the Desktop app runs a local
+**BlueBubbles bridge** — a small HTTP server in the Electron main process that
+registers a webhook on a local [BlueBubbles](https://bluebubbles.app/) server,
+receives iMessage events, and forwards them to LobeHub Cloud.
+
+So the test surface is three layers:
+
+1. **Electron main IPC** — `imessageBridge.*` handlers (`getStatus`,
+   `testConfig`, `upsertConfig`, `removeConfig`, `start`, `stop`)
+2. **Local bridge HTTP server** — `http://127.0.0.1:<port>/webhooks/bluebubbles/<appId>?secret=<secret>`
+3. **BlueBubbles REST API** — `http://127.0.0.1:1234/api/v1/*` (webhook + server/info)
+
+## Prerequisites
+
+- A running **BlueBubbles server** (macOS, default `http://127.0.0.1:1234`) with
+  a known password. Sanity check:
+  ```bash
+  curl -sS -m4 -o /dev/null -w '%{http_code}\n' \
+    "http://127.0.0.1:1234/api/v1/server/info?password=<PW>" # expect 200
+  ```
+- **Electron dev running with CDP**: `./.agents/skills/local-testing/scripts/electron-dev.sh start`
+- The **iMessage Desktop branch** checked out (the `imessageBridge` IPC group
+  and `@lobechat/chat-adapter-imessage` must be compiled into the main bundle).
+  Run `pnpm install --ignore-scripts` at the repo root **and** in `apps/desktop/`
+  after switching branches — the new workspace package must be linked or the
+  main build fails to resolve `@lobechat/chat-adapter-imessage`.
+
+## Fast path: automated script
+
+```bash
+./.agents/skills/local-testing/bot/imessage/test-imessage-bridge.sh '<bluebubbles_password>' [bb_url] [cdp_port]
+```
+
+Asserts the whole flow and self-cleans (unique `applicationId` per run, removes
+its bridge config + BlueBubbles webhook on exit). Exit 0 = all green. It covers:
+
+- BlueBubbles reachable + password valid; Electron CDP reachable; IPC available
+- `testConfig` happy path → success
+- `testConfig` wrong password → rejected; unreachable URL → rejected
+- `upsertConfig` **first-time save → success** (Bug #1 regression guard, below)
+- `getStatus` → `running:true`, config persisted, password redacted (`blueBubblesPasswordSet`)
+- BlueBubbles webhook actually registered for the appId
+- Local bridge HTTP server: wrong secret → 401; valid secret → past auth
+
+The password is passed as argv (visible in `ps`) — local dev only, don't use a
+real secret on a shared machine.
+
+## Layer 1 — IPC probes (no UI)
+
+The renderer exposes the main-process handlers via `window.electronAPI.invoke`.
+This is the quickest way to exercise the bridge without clicking:
+
+```bash
+# baseline
+agent-browser --cdp 9222 eval \
+  "(async()=>JSON.stringify(await window.electronAPI.invoke('imessageBridge.getStatus',{})))()"
+
+# test a connection (note: password as a JS string)
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(async function () {
+  try {
+    var r = await window.electronAPI.invoke('imessageBridge.testConfig', {
+      applicationId: 'probe',
+      blueBubblesServerUrl: 'http://127.0.0.1:1234',
+      blueBubblesPassword: 'PASTE_PW',
+      enabled: true,
+      webhookSecret: 'probe-secret',
+    });
+    return JSON.stringify(r);            // { success: true }
+  } catch (e) { return 'ERR: ' + (e.message || e); }
+})()
+EVALEOF
+```
+
+`upsertConfig` persists to the Electron store, starts the local HTTP server, and
+registers the BlueBubbles webhook. `removeConfig` + `stop` reverse it.
+
+## Layer 2 — full UI flow (agent-browser)
+
+The bridge settings only render in Desktop (`isDesktop` guard) under the agent's
+**Channel → iMessage** screen. The platform tile only appears as a real (non
+"Coming Soon") entry once the server registers `imessage` **and** the frontend
+drops it from `COMING_SOON_PLATFORMS` (`src/routes/(main)/agent/channel/const.ts`).
+
+```bash
+agent-browser --cdp 9222 open "http://localhost:5173/agent/<aid>/channel"
+agent-browser --cdp 9222 wait --load networkidle && agent-browser --cdp 9222 wait 1500
+
+# confirm the remote backend lists imessage (it must be registered + deployed)
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(async function(){
+  var url='lobe-backend://lobe/trpc/lambda/agentBotProvider.listPlatforms?input='+encodeURIComponent('{"json":null,"meta":{"values":["undefined"],"v":1}}');
+  var d=await (await fetch(url,{credentials:'include'})).json();
+  var p=d.result?.data?.json||d;
+  return JSON.stringify(p.map(function(x){return x.id;}));
+})()
+EVALEOF
+
+# click the iMessage tile, then fill the form by ref
+agent-browser --cdp 9222 eval "(()=>{var b=[...document.querySelectorAll('aside button')].find(x=>/imessage/i.test(x.textContent));b&&b.click();})()"
+agent-browser --cdp 9222 wait 1500
+agent-browser --cdp 9222 snapshot -i | grep -iE "127.0.0.1:1234|Application ID|Webhook Secret|Test BlueBubbles|Save Bridge"
+```
+
+Field refs (from the snapshot): Application ID, Webhook Secret, BlueBubbles
+Server URL (`placeholder="http://127.0.0.1:1234"`), and a **nested** textbox right
+under the URL one is the BlueBubbles Password. Fill with `fill` (real input
+events — `eval`-setting React inputs won't fire onChange), click **Test
+BlueBubbles**, then **Save Bridge**. Read the antd toast immediately (it
+auto-dismisses):
+
+```bash
+agent-browser --cdp 9222 eval \
+  "JSON.stringify([...new Set([...document.querySelectorAll('.ant-message-custom-content')].map(n=>n.textContent.trim()))])"
+# Test  → "BlueBubbles connection passed"
+# Save  → "iMessage Desktop bridge saved"
+```
+
+Verify the end state via BlueBubbles + IPC:
+
+```bash
+curl -sS "http://127.0.0.1:1234/api/v1/webhook?password=<PW>" # webhook for the appId present
+agent-browser --cdp 9222 eval "(async()=>JSON.stringify(await window.electronAPI.invoke('imessageBridge.getStatus',{})))()"
+# running:true, serverUrl: http://127.0.0.1:33270, configs[].blueBubblesPasswordSet:true
+```
+
+Cleanup: `removeConfig` + `stop` via IPC, then `DELETE /api/v1/webhook/<id>` on
+BlueBubbles.
+
+## Outbound send test (desktop → BlueBubbles → iMessage)
+
+Verifies the leg the bridge uses to _reply_: `BlueBubblesApiClient.sendText`
+→ `POST /api/v1/message/text`. Run the helper against your own number:
+
+```bash
+./.agents/skills/local-testing/bot/imessage/send-imessage-test.sh '<bb_password>' '+<E164>' # e.g. +15551234567
+```
+
+**Gotcha that bites everyone:** with `method=apple-script` and a _new_
+conversation, the HTTP POST often **times out** even though the message is
+sent. Never judge success by the HTTP response. Instead poll
+`POST /api/v1/message/query` and read the matching `isFromMe:true` row's
+`error` field:
+
+- `error: 0` (or null) → sent OK
+- non-zero `error` → real send failure
+
+The script does exactly this: fires the send, ignores the timeout, then matches
+its marker text in the message store and asserts `error == 0`.
+
+Two more notes:
+
+- Use a full E.164 handle (`iMessage;-;+<countrycode><number>`) or an Apple ID
+  email. Looking the chat up by guid afterwards may 404 if BB filed the message
+  under a differently-formatted guid — that's a lookup quirk, not a send failure.
+- Sending to _your own_ number round-trips: BB records both the outgoing
+  (`fromMe:true`) and an incoming copy (`fromMe:false`).
+
+## Inbound e2e test (iMessage → cloud agent → reply)
+
+Full inbound chain: a message arrives → BlueBubbles fires its `new-message`
+webhook → local bridge (`:33270`) → `forwardWebhook` POSTs to
+`<remote>/api/agent/webhooks/imessage/<appId>?secret=…` → cloud agent → reply
+flows back via Device Gateway → BB `sendText`.
+
+Prerequisites:
+
+- A cloud bot provider for the same `applicationId` exists and is **connected**
+  (Save Configuration + the device gateway connected — a _disconnected_ gateway
+  yields `DEVICE_NOT_FOUND` on connect and blocks the reply leg).
+- The `imessage` Labs toggle is on (otherwise the channel is gated to "Coming
+  Soon"), and `webhookSecret` matches on both ends (auto-generated on save).
+
+Two ways to drive it:
+
+1. **Second device / Apple ID (recommended).** Have _another_ Apple ID message
+   the BB-hosted number (e.g. "please reply pong"). The bot replies; you see it
+   on the other device. **No loop risk** — the reply goes to the other party,
+   not back to itself.
+2. **Send to your own number (quick, loop-aware).** `sendText` to the hosted
+   number; the loopback _incoming_ copy (`isFromMe:false`) triggers the bot.
+   Watch the reply land in `message/query` as a `fromMe:true` row.
+
+**Loop guard — why a self-send doesn't spin forever:** the Chat SDK adapter
+drops any `isFromMe` message before dispatch
+(`packages/chat-adapter-imessage/src/adapter.ts`: `if (message.isFromMe) return`).
+The bot's own reply (`isFromMe:true`) is never re-processed, so in the normal
+case (someone else → bot → reply to them) there is no loop. The self-send case
+is a **test-only edge**: the bot's reply also round-trips to your number, and
+only the adapter's `isFromMe` check stops a second pass. Keep the prompt
+conversational (so the bot doesn't keep finding something to answer), and
+**turn the `imessage` lab off / remove the config when done** — never leave a
+self-send bot running unattended.
+
+Watch the chain live:
+
+```bash
+tail -f /tmp/electron-dev.log | grep -iE "imessage|bridge|forward|Message API"
+# the agent reply shows up as a fromMe:true row with the bot's text:
+curl -sS -X POST "http://127.0.0.1:1234/api/v1/message/query?password=<PW>" \
+  -H 'Content-Type: application/json' -d '{"limit":5,"sort":"DESC"}'
+```
+
+`startTyping` will log a Private-API error unless BlueBubbles has the Private
+API helper set up (needs a jailbroken / SIP-disabled Mac) — it's logged and
+ignored; text replies still work.
+
+## Known bugs / gotchas
+
+- **Bug #1 — first-time save (fixed; guarded by the script).** BlueBubbles'
+  `GET /api/v1/webhook?url=<unregistered>` returns **HTTP 500**
+  (`Cannot read properties of null (reading 'events')`). The bridge must list
+  **all** webhooks and match client-side, never pass the `?url=` filter. If you
+  see `upsertConfig` fail with "An unhandled error has occurred!" originating in
+  `listWebhooks`, this regressed.
+- **Save leaves a half-state on webhook failure.** `upsertConfig` writes the
+  config + starts the HTTP server _before_ registering the webhook, so a webhook
+  failure still reports `running:true` with the config persisted but no
+  BlueBubbles webhook. Always assert the BlueBubbles webhook list, not just IPC
+  status.
+- **Unknown appId / forward failure → 500.** Posting to the local bridge for an
+  unknown appId, or when no cloud bot is bound, returns 500 (BlueBubbles retries
+  on 5xx). Auth (wrong secret → 401) is enforced before that.
+- **Backend deploy lag.** Desktop dev proxies tRPC through `lobe-backend://` to
+  the _remote_ server. iMessage only appears in `listPlatforms` once the server
+  registration is deployed there, regardless of local branch.
+- **Restart to load main-process fixes.** Editing `imessageBridgeSrv.ts` /
+  `@lobechat/chat-adapter-imessage` needs `electron-dev.sh restart` — main isn't
+  hot-replaced. On restart, enabled configs auto-register their webhook again.

.agents/skills/local-testing/bot/imessage/send-imessage-test.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# send-imessage-test.sh — Verify the outbound leg: desktop → BlueBubbles → iMessage
+#
+# Sends one real iMessage via the same REST call the Desktop bridge uses
+# (`POST /api/v1/message/text`, which BlueBubblesApiClient.sendText wraps) and
+# confirms it actually went out.
+#
+# KEY GOTCHA: with method=apple-script and a NEW conversation, the HTTP request
+# often TIMES OUT even though the message is sent. Do NOT treat the timeout as a
+# failure — instead poll `POST /api/v1/message/query` and check the message's
+# `error` field (0 = sent OK). This script does that for you.
+#
+# This sends a REAL message, so it has side effects. Target your own number.
+#
+# Usage:
+#   ./send-imessage-test.sh <bb_password> <target_e164> [message] [bb_url]
+#
+# Example (send to your own phone, E.164 with country code):
+#   ./send-imessage-test.sh 'my-bb-pass' '+15551234567'
+#
+set -euo pipefail
+
+BB_PASS="${1:?Usage: $0 <bb_password> <target_e164(+countrycode)> [message] [bb_url]}"
+TARGET="${2:?Need a target handle in E.164, e.g. +15551234567 (or an Apple ID email)}"
+MARKER="lobe-imsg-test-$(date +%s)"
+MESSAGE="${3:-[${MARKER}] desktop bridge → BlueBubbles → iMessage outbound check}"
+BB_URL="${4:-http://127.0.0.1:1234}"
+
+CHAT_GUID="iMessage;-;${TARGET}"
+
+echo "[send-test] target=${TARGET}  marker=${MARKER}"
+
+# 1) Fire the send. apple-script on a new chat may hang the HTTP response, so we
+#    cap it short and ignore a timeout — step 2 is the source of truth.
+python3 - "$BB_PASS" "$BB_URL" "$CHAT_GUID" "$MESSAGE" <<'PY' || true
+import json,sys,urllib.request,urllib.parse,uuid
+pw,base,guid,msg=sys.argv[1:5]
+url=base+"/api/v1/message/text?password="+urllib.parse.quote(pw)
+body={"chatGuid":guid,"message":msg,"method":"apple-script","tempGuid":str(uuid.uuid4())}
+req=urllib.request.Request(url,data=json.dumps(body).encode("utf-8"),
+    headers={"Content-Type":"application/json"},method="POST")
+try:
+    r=urllib.request.urlopen(req,timeout=8)
+    print("[send-test] HTTP",r.status,"(immediate response)")
+except urllib.error.HTTPError as e:
+    print("[send-test] HTTP",e.code,e.read().decode()[:200])
+except Exception as e:
+    print("[send-test] HTTP request returned no body (likely apple-script delay):",type(e).__name__)
+PY
+
+# 2) Source of truth: find our marker in the message store and read its error.
+echo "[send-test] verifying via message/query (the HTTP timeout above is expected)…"
+sleep 3
+python3 - "$BB_PASS" "$BB_URL" "$MARKER" <<'PY'
+import json,sys,time,urllib.request,urllib.parse
+pw,base,marker=sys.argv[1:4]
+url=base+"/api/v1/message/query?password="+urllib.parse.quote(pw)
+def query():
+    body={"limit":15,"offset":0,"with":["chats"],"sort":"DESC"}
+    req=urllib.request.Request(url,data=json.dumps(body).encode(),
+        headers={"Content-Type":"application/json"},method="POST")
+    return json.load(urllib.request.urlopen(req,timeout=12)).get("data") or []
+hit=None
+for _ in range(5):
+    for m in query():
+        if marker in (m.get("text") or "") and m.get("isFromMe"):
+            hit=m; break
+    if hit: break
+    time.sleep(2)
+if not hit:
+    print("[send-test] ✗ outbound message not found in BB store — send likely failed")
+    sys.exit(1)
+err=hit.get("error")
+if err in (0,None):
+    print("[send-test] ✓ outbound message sent (fromMe=True, error=%s)"%err)
+    print("[send-test]   → confirm it arrived in the Messages app on the target device")
+else:
+    print("[send-test] ✗ BlueBubbles reported send error=%s"%err)
+    sys.exit(1)
+PY

.agents/skills/local-testing/bot/imessage/test-imessage-bridge.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+#
+# test-imessage-bridge.sh — Regression test for the iMessage Desktop bridge
+#
+# Drives the Electron main-process `imessageBridge.*` IPC handlers plus the
+# local bridge HTTP server and the BlueBubbles server, asserting the full
+# connect/configure flow. Use it to regression-test PR work on the iMessage
+# channel (BlueBubbles bridge) without clicking through the UI every time.
+#
+# Prerequisites:
+#   1. BlueBubbles server running and reachable (default http://127.0.0.1:1234)
+#   2. Electron dev running with CDP — `electron-dev.sh start`
+#   3. `agent-browser` on PATH, connected to the same CDP port
+#
+# Usage:
+#   ./test-imessage-bridge.sh <bluebubbles_password> [bb_url] [cdp_port]
+#
+# Example:
+#   ./test-imessage-bridge.sh 'my-bb-password'
+#   ./test-imessage-bridge.sh 'my-bb-password' http://127.0.0.1:1234 9222
+#
+# Notes:
+#   - The password is passed as an argv, so it is visible in `ps`. This is a
+#     local dev tool; do not run it on shared machines with a real secret.
+#   - It uses a unique applicationId per run (imsg-regression-$$) and cleans up
+#     its own bridge config + BlueBubbles webhook on exit, so it is safe to
+#     re-run and does not disturb real configs.
+set -euo pipefail
+
+BB_PASS="${1:?Usage: $0 <bluebubbles_password> [bb_url] [cdp_port]}"
+BB_URL="${2:-http://127.0.0.1:1234}"
+CDP_PORT="${3:-9222}"
+
+APP_ID="imsg-regression-$$"
+SECRET="regression-secret-$$"
+
+PASS=0
+FAIL=0
+
+# ── Output helpers ───────────────────────────────────────────────────
+ok()   { echo "  ✓ $1"; PASS=$((PASS + 1)); }
+bad()  { echo "  ✗ $1 — $2"; FAIL=$((FAIL + 1)); }
+note() { echo "[imsg-test] $1"; }
+
+# ── BlueBubbles REST helpers ─────────────────────────────────────────
+bb_get_webhooks() {
+  curl -sS -m 8 "${BB_URL}/api/v1/webhook?password=${BB_PASS}"
+}
+
+# Delete every webhook whose URL mentions our APP_ID (cleanup is idempotent).
+bb_cleanup_webhooks() {
+  local ids
+  ids=$(bb_get_webhooks | python3 -c '
+import json,sys
+try: d=json.load(sys.stdin)
+except Exception: sys.exit(0)
+for w in (d.get("data") or []):
+    if "'"$APP_ID"'" in (w.get("url") or ""): print(w["id"])
+' 2>/dev/null || true)
+  for id in $ids; do
+    curl -sS -m 8 -X DELETE "${BB_URL}/api/v1/webhook/${id}?password=${BB_PASS}" >/dev/null 2>&1 || true
+  done
+}
+
+# ── IPC helper (drives the Electron renderer's electronAPI bridge) ───
+# Runs a JS snippet that returns a string token; prints the raw token.
+# The BlueBubbles password is base64-injected (atob) so special chars in the
+# secret never need shell/JS quoting.
+ipc_eval() {
+  local js="$1"
+  agent-browser --cdp "$CDP_PORT" eval -b "$(printf '%s' "$js" | base64)" 2>/dev/null
+}
+
+PASS_B64=$(printf '%s' "$BB_PASS" | base64)
+
+# Emit an inline JS object literal for the bridge config. $1 overrides the
+# password expression (defaults to atob of the real password); pass a JS string
+# literal like "'wrong'" to test the rejection path.
+ipc_config_js() {
+  local pwexpr="${1:-atob('${PASS_B64}')}"
+  printf "{applicationId:'%s',blueBubblesServerUrl:'%s',blueBubblesPassword:%s,enabled:true,webhookSecret:'%s'}" \
+    "$APP_ID" "$BB_URL" "$pwexpr" "$SECRET"
+}
+
+# ── Preflight ────────────────────────────────────────────────────────
+note "BlueBubbles: ${BB_URL}   CDP: ${CDP_PORT}   appId: ${APP_ID}"
+
+code=$(curl -sS -m 6 -o /dev/null -w '%{http_code}' \
+  "${BB_URL}/api/v1/server/info?password=${BB_PASS}" || echo 000)
+if [ "$code" = "200" ]; then ok "BlueBubbles reachable + password valid"; else
+  bad "BlueBubbles preflight" "HTTP $code (is BlueBubbles running on ${BB_URL}?)"
+  echo "Aborting — fix BlueBubbles first."; exit 1
+fi
+
+if ! curl -sf --max-time 3 "http://localhost:${CDP_PORT}/json/version" >/dev/null 2>&1; then
+  bad "Electron CDP preflight" "CDP ${CDP_PORT} unreachable — run electron-dev.sh start"
+  echo "Aborting."; exit 1
+fi
+ok "Electron CDP reachable"
+
+# Bridge must expose the IPC group (built from this branch's code).
+probe=$(ipc_eval "(async()=>{try{var s=await window.electronAPI.invoke('imessageBridge.getStatus',{});return 'OK:'+JSON.stringify(s);}catch(e){return 'ERR:'+(e.message||e);}})()")
+case "$probe" in
+  *OK:*) ok "imessageBridge IPC available" ;;
+  *) bad "imessageBridge IPC" "got: $probe (is the iMessage Desktop branch checked out?)"; echo "Aborting."; exit 1 ;;
+esac
+
+# Start clean: remove any leftover config for this appId + BB webhooks.
+ipc_eval "(async()=>{try{await window.electronAPI.invoke('imessageBridge.removeConfig',{applicationId:'${APP_ID}'});}catch(e){}return 'done';})()" >/dev/null
+bb_cleanup_webhooks
+
+# ── testConfig: happy path ───────────────────────────────────────────
+r=$(ipc_eval "(async()=>{try{var c=$(ipc_config_js);var x=await window.electronAPI.invoke('imessageBridge.testConfig',c);return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
+case "$r" in
+  *OK:*success*true*) ok "testConfig with valid password → success" ;;
+  *) bad "testConfig (valid)" "got: $r" ;;
+esac
+
+# ── testConfig: wrong password rejects ───────────────────────────────
+r=$(ipc_eval "(async()=>{try{var c=$(ipc_config_js "'definitely-wrong-password'");var x=await window.electronAPI.invoke('imessageBridge.testConfig',c);return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
+case "$r" in
+  *ERR:*) ok "testConfig with wrong password → rejected" ;;
+  *) bad "testConfig (wrong password)" "expected rejection, got: $r" ;;
+esac
+
+# ── testConfig: unreachable URL rejects ──────────────────────────────
+r=$(ipc_eval "(async()=>{try{var x=await window.electronAPI.invoke('imessageBridge.testConfig',{applicationId:'${APP_ID}',blueBubblesServerUrl:'http://127.0.0.1:65530',blueBubblesPassword:atob('${PASS_B64}'),enabled:true,webhookSecret:'${SECRET}'});return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
+case "$r" in
+  *ERR:*) ok "testConfig with unreachable URL → rejected" ;;
+  *) bad "testConfig (unreachable)" "expected rejection, got: $r" ;;
+esac
+
+# ── upsertConfig: FIRST-TIME registration (Bug #1 regression guard) ──
+# BlueBubbles' GET /webhook?url=<unregistered> returns HTTP 500. The bridge
+# must list ALL webhooks and match client-side, otherwise this first save
+# fails. This assertion guards that fix.
+r=$(ipc_eval "(async()=>{try{var c=$(ipc_config_js);var x=await window.electronAPI.invoke('imessageBridge.upsertConfig',c);return 'OK:'+JSON.stringify(x);}catch(e){return 'ERR:'+(e.message||e);}})()")
+case "$r" in
+  *OK:*success*true*) ok "upsertConfig first-time save → success (Bug #1 guard)" ;;
+  *) bad "upsertConfig (first-time)" "got: $r" ;;
+esac
+
+# ── getStatus: bridge running + config persisted ─────────────────────
+# Return a quote-free token so grep isn't tripped up by agent-browser's
+# JSON-string escaping of the eval result.
+r=$(ipc_eval "(async()=>{var s=await window.electronAPI.invoke('imessageBridge.getStatus',{});var c=(s.configs||[]).find(function(x){return x.applicationId==='${APP_ID}';});return 'RUN='+(s.running?'Y':'N')+' CFG='+(c?'Y':'N')+' PW='+((c&&c.blueBubblesPasswordSet)?'Y':'N');})()")
+echo "$r" | grep -q 'RUN=Y' && ok "bridge running" || bad "bridge running" "got: $r"
+echo "$r" | grep -q 'CFG=Y' && ok "config persisted" || bad "config persisted" "got: $r"
+echo "$r" | grep -q 'PW=Y'  && ok "password stored (redacted in status)" || bad "password stored" "got: $r"
+
+# ── BlueBubbles webhook actually registered ──────────────────────────
+if bb_get_webhooks | grep -q "${APP_ID}"; then
+  ok "BlueBubbles webhook registered for appId"
+else
+  bad "BlueBubbles webhook" "no webhook URL containing ${APP_ID}"
+fi
+
+# ── Local bridge HTTP server: secret enforcement ─────────────────────
+BRIDGE_URL=$(ipc_eval "(async()=>{var s=await window.electronAPI.invoke('imessageBridge.getStatus',{});return s.serverUrl||'';})()" | tr -d '"')
+if [ -n "$BRIDGE_URL" ]; then
+  # wrong secret → 401
+  code=$(curl -sS -m 6 -o /dev/null -w '%{http_code}' -X POST \
+    -H 'Content-Type: application/json' \
+    "${BRIDGE_URL}/webhooks/bluebubbles/${APP_ID}?secret=WRONG" \
+    -d '{"type":"new-message","data":{"guid":"x"}}' || echo 000)
+  [ "$code" = "401" ] && ok "local bridge rejects wrong secret (401)" || bad "local bridge wrong secret" "expected 401, got $code"
+
+  # right secret → passes auth (reaches forward; without a bound cloud bot it
+  # returns 5xx — that's fine, we're only asserting auth + routing here)
+  code=$(curl -sS -m 6 -o /dev/null -w '%{http_code}' -X POST \
+    -H 'Content-Type: application/json' \
+    "${BRIDGE_URL}/webhooks/bluebubbles/${APP_ID}?secret=${SECRET}" \
+    -d '{"type":"new-message","data":{"guid":"x","text":"hi"}}' || echo 000)
+  [ "$code" != "401" ] && ok "local bridge accepts valid secret (HTTP $code, past auth)" || bad "local bridge valid secret" "got 401 with correct secret"
+else
+  bad "local bridge URL" "getStatus returned no serverUrl"
+fi
+
+# ── Cleanup ──────────────────────────────────────────────────────────
+ipc_eval "(async()=>{try{await window.electronAPI.invoke('imessageBridge.removeConfig',{applicationId:'${APP_ID}'});await window.electronAPI.invoke('imessageBridge.stop',{});}catch(e){}return 'cleaned';})()" >/dev/null
+bb_cleanup_webhooks
+note "cleaned up config + BlueBubbles webhook for ${APP_ID}"
+
+# ── Summary ──────────────────────────────────────────────────────────
+echo ""
+echo "[imsg-test] PASS=${PASS}  FAIL=${FAIL}"
+[ "$FAIL" -eq 0 ] || exit 1

.agents/skills/local-testing/bot/lark/index.md

@@ -2,7 +2,7 @@
 
 **App name:** `Lark` or `飞书` | **Process name:** `Lark` or `飞书`
 
-See [osascript-common.md](./osascript-common.md) for shared patterns.
+See [osascript-common.md](../osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -56,6 +56,6 @@ screencapture /tmp/lark-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "@MyBot hello"
-./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "Help me with this" 30
+./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "@MyBot hello"
+./.agents/skills/local-testing/bot/lark/test-lark-bot.sh "bot-testing" "Help me with this" 30
 ```

.agents/skills/local-testing/bot/lark/test-lark-bot.sh

@@ -80,5 +80,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/bot/qq/index.md

@@ -2,7 +2,7 @@
 
 **App name:** `QQ` | **Process name:** `QQ`
 
-See [osascript-common.md](./osascript-common.md) for shared patterns.
+See [osascript-common.md](../osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -57,6 +57,6 @@ screencapture /tmp/qq-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/scripts/test-qq-bot.sh "bot-testing" "Hello bot" 15
-./.agents/skills/local-testing/scripts/test-qq-bot.sh "MyBot" "/help" 10
+./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "bot-testing" "Hello bot" 15
+./.agents/skills/local-testing/bot/qq/test-qq-bot.sh "MyBot" "/help" 10
 ```

.agents/skills/local-testing/bot/qq/test-qq-bot.sh

@@ -72,5 +72,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/bot/slack/index.md

@@ -2,7 +2,7 @@
 
 **App name:** `Slack` | **Process name:** `Slack`
 
-See [osascript-common.md](./osascript-common.md) for shared patterns.
+See [osascript-common.md](../osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -68,6 +68,6 @@ screencapture /tmp/slack-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "@mybot hello"
-./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
+./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "@mybot hello"
+./.agents/skills/local-testing/bot/slack/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
 ```

.agents/skills/local-testing/bot/slack/test-slack-bot.sh

@@ -60,5 +60,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/bot/telegram/index.md

@@ -2,7 +2,7 @@
 
 **App name:** `Telegram` | **Process name:** `Telegram`
 
-See [osascript-common.md](./osascript-common.md) for shared patterns.
+See [osascript-common.md](../osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -75,6 +75,6 @@ curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?limit=5" | j
 ## Script
 
 ```bash
-./.agents/skills/local-testing/scripts/test-telegram-bot.sh "MyTestBot" "/start"
-./.agents/skills/local-testing/scripts/test-telegram-bot.sh "GPTBot" "Hello" 60
+./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "MyTestBot" "/start"
+./.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh "GPTBot" "Hello" 60
 ```

.agents/skills/local-testing/bot/telegram/test-telegram-bot.sh

@@ -75,5 +75,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/local-testing/bot/wechat/index.md

@@ -2,7 +2,7 @@
 
 **App name:** `微信` or `WeChat` | **Process name:** `WeChat`
 
-See [osascript-common.md](./osascript-common.md) for shared patterns.
+See [osascript-common.md](../osascript-common.md) for shared patterns.
 
 ## Activate & Navigate
 
@@ -76,6 +76,6 @@ screencapture /tmp/wechat-bot-response.png
 ## Script
 
 ```bash
-./.agents/skills/local-testing/scripts/test-wechat-bot.sh "文件传输助手" "test message" 5
-./.agents/skills/local-testing/scripts/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
+./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "文件传输助手" "test message" 5
+./.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
 ```

.agents/skills/local-testing/bot/wechat/test-wechat-bot.sh

@@ -81,5 +81,5 @@ echo "[$APP] Waiting ${WAIT}s for bot response..."
 sleep "$WAIT"
 
 echo "[$APP] Capturing screenshot..."
-"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+"$SCRIPT_DIR/../capture-app-window.sh" "$APP" "$SCREENSHOT"
 echo "[$APP] Done! Screenshot saved to $SCREENSHOT"

.agents/skills/microcopy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: microcopy
-description: UI copy and microcopy guidelines. Use when writing UI text, buttons, error messages, empty states, onboarding, or any user-facing copy. Triggers on i18n translation, UI text writing, or copy improvement tasks. Supports both Chinese and English.
+description: 'UI copy and microcopy guidelines. Use for user-facing copy, buttons, errors, empty states, onboarding, i18n wording, translation, or copy improvements in Chinese or English.'
 user-invocable: false
 ---
 

.agents/skills/modal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modal
-description: "LobeHub imperative-modal conventions. Use whenever creating, editing, opening, or migrating a modal/dialog/popup — prefer `createModal` / `confirmModal` / `useModalContext` from `@lobehub/ui/base-ui` (headless) over the legacy root `@lobehub/ui` `createModal` (antd Modal props) and over any declarative `open` state + `<Modal />` pattern. Covers required `ModalHost` mounting, the `Content` + `index.tsx` file layout, `content` vs `children` slot, i18n inside `createModal()` (`import { t } from 'i18next'`), and migration notes. Triggers on `createModal`, `confirmModal`, `useModalContext`, `ModalHost`, `antd Modal`, `<Modal open>`, 'open a modal', 'popup', 'dialog', 'confirm dialog', '弹框', '弹窗', '确认框', 'migrate to base-ui'."
+description: 'LobeHub imperative modal conventions. Use when creating or migrating modals, dialogs, popups, confirm flows, ModalHost wiring, createModal, confirmModal, useModalContext, or base-ui modal APIs.'
 user-invocable: false
 ---
 

.agents/skills/pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr
-description: "Create a PR for the current branch (targets `canary` by default). Use when the user asks to create a pull request, submit a PR, or says 'pr'. Triggers on 'pr', 'create pr', 'submit pr', 'open a PR', 'pull request', '提 PR', '提个 PR', '新建 PR'."
+description: "Create a PR for the current branch (targets `canary` by default), including splitting one cross-layer branch into ordered stacked PRs so a lower layer (db / shared package / server TRPC) merges before its callers (desktop / CLI / UI). Use when the user asks to create / submit a PR, or to split a branch because clients call a server contract that isn't on the trunk yet. Triggers on 'pr', 'create pr', 'submit pr', 'open a PR', 'pull request', 'split this PR', 'stacked PR', 'backend should merge first', '提 PR', '提个 PR', '新建 PR', '拆 PR', '后端先合', '分层合并'."
 user-invocable: true
 ---
 
@@ -71,3 +71,82 @@ Use `.github/PULL_REQUEST_TEMPLATE.md` as the body structure. Key sections:
 
 - **Language**: All PR content must be in English
 - If a PR already exists for the branch, inform the user instead of creating a duplicate
+
+---
+
+# Stacked PRs (cross-layer feature)
+
+The steps above create **one** PR for the current branch. When a single branch lands across layers — `packages/database` schema/model → a shared `packages/*` lib → `src/server` TRPC → `apps/desktop` + `apps/cli` callers → `src/features` UI — shipping it as one PR can't merge safely: the clients call an endpoint that doesn't exist on the trunk until the same PR merges, so any partial/rollback or independent review breaks. Split it into **ordered PRs**, lower layer first.
+
+## The ordering rule
+
+A PR may only merge **after** every layer it calls is already on the trunk.
+
+- The **server contract** (new TRPC procedure, changed return shape, new table/model) merges first.
+- The **callers** (desktop, CLI, UI) merge after — they invoke that contract.
+- Tie-break with one question: _"if this merged alone to `canary` right now, would it build and behave?"_ If no, it belongs in a later PR.
+
+## Which file goes in which PR
+
+The non-obvious calls:
+
+- **Frontend that adapts to a contract change goes WITH the server PR.** If you widen a TRPC return shape (e.g. `listDevices` now returns `platform: string | null`), the component consuming it must change in the _same_ PR — otherwise the server PR breaks the build on its own. Contract + its in-repo consumers ship together.
+- **A new shared package goes with its consumer**, not the server, unless the server imports it too. A `@lobechat/*` package imported only by desktop/CLI ships in the client PR. Don't carry an unused package in the lower PR.
+- **Workspace dep declarations** (`package.json` `workspace:*`, `pnpm-workspace.yaml`) travel with the code that imports the package.
+
+## The git recipe — split an existing full branch
+
+Starting point: one branch (`feat/x`) with a single commit `<FULL>` containing everything, already pushed (so it's also safe on the remote).
+
+```bash
+# 1. Safety nets — make the full work unloseable before rewriting anything
+git branch backup/x-full <FULL>          # local ref to the full commit
+git branch feat/x-clients <FULL>         # the higher-layer branch starts here
+
+# 2. Rewrite the lower-layer branch to lower-layer files only
+git checkout feat/x                      # this becomes the SERVER PR
+git reset --hard origin/canary
+git checkout <FULL> -- <server/db files…>   # stages just those paths
+git commit -m "✨ feat(...): <server half>"
+git push --force-with-lease origin feat/x   # never --force; never push to canary
+
+# 3. Build the higher-layer branch STACKED on the lower branch
+git checkout feat/x-clients
+git reset --hard feat/x                  # base = the just-rewritten server HEAD
+git checkout backup/x-full -- <client/ui files…>   # only the remaining paths
+git commit -m "✨ feat(...): <client half>"
+git push -u origin feat/x-clients
+```
+
+Then open the higher PR **based on the lower branch**, not the trunk:
+
+```bash
+gh pr create --base feat/x --head feat/x-clients --title "…" --body "…"
+```
+
+`--base feat/x` keeps the diff client-only (no server files leak in) and makes it physically impossible to merge the clients before the server. **After the server PR merges to `canary`, retarget the client PR's base to `canary`** (GitHub usually auto-retargets when the base branch merges; note it in the PR body so a human confirms).
+
+## Verify the dependency actually holds
+
+The whole point is the higher layer needs the lower one. Prove it: on the stacked higher branch, type-check the caller and confirm the symbol the lower layer introduced resolves.
+
+```bash
+cd apps/cli && bun run type-check 2>&1 | grep -iE "connect\.ts|device\.register"
+# empty (re: your change) = the stacked base supplies device.register ✓
+```
+
+Filter to your touched files — this repo's standalone type-check emits pre-existing env noise (`__ELECTRON__`, `@/types/llm`, unbuilt `@lobechat/types`) that isn't yours.
+
+## PR + Linear bookkeeping
+
+- **Each PR closes only its own layer's issues.** Server PR: `Closes LOBE-<server>`. Client PR: `Closes LOBE-<pkg> / <desktop> / <cli>`. Don't let one PR's body claim another layer's issue.
+- Both PRs are `Part of LOBE-<parent>`.
+- On PR creation, move each closed sub-issue to **In Review** (not Done) and add a completion comment — see the `linear` skill.
+
+## Gotchas
+
+- **Never push to `canary`.** A split branch cut with `git checkout -b feat/x origin/canary` _tracks_ `origin/canary`, so a bare `git push` targets canary. Always `git push origin feat/x` with the explicit branch name.
+- **`--force-with-lease`, not `--force`** when rewriting the lower branch — it aborts if the remote moved under you.
+- **Back up before `reset --hard`.** Step 1's `backup/x-full` + the pushed remote branch mean the full commit is referenced by ≥3 refs before you rewrite anything. Verify with `git branch --contains <FULL>`.
+- **Lockfiles:** this monorepo commits no root `pnpm-lock.yaml`, so a new `workspace:*` dep needs no lockfile churn. In a repo that _does_ commit one, regenerate it on each branch after the split.
+- **Don't over-split.** Two PRs (contract / callers) is usually enough. A UI page that only reads an existing endpoint can be its own later PR, but don't fragment a single layer across PRs for its own sake.

.agents/skills/project-overview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-overview
-description: "LobeHub open-source monorepo architecture map — flat `apps/` + `packages/@lobechat/*` + `src/` layout, per-layer location table, and `src/business/` stubs that the cloud repo overrides. Use when exploring an unfamiliar part of the codebase, locating where a layer lives (store / service / router / schema / etc.), or onboarding to the monorepo. Triggers on 'where does X live', 'project structure', 'monorepo layout', `src/business/` stub, 'architecture overview', '项目结构', '架构总览'."
+description: 'LobeHub open-source monorepo architecture map. Use when locating code layers, understanding apps/packages/src layout, business stubs, project structure, or onboarding to the repository.'
 user-invocable: false
 ---
 

.agents/skills/react/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: react
-description: "LobeHub React component conventions — base-ui (`@lobehub/ui/base-ui`) first for headless primitives (Select, Modal, DropdownMenu, ContextMenu, Popover, ScrollArea, Switch, Toast, FloatingSheet), then `@lobehub/ui` root, antd as last resort; styling via `antd-style` `createStaticStyles` + `cssVar.*` (zero-runtime preferred over `createStyles` + `token`); routing via `react-router-dom` (not `next/link`). Use when writing or editing any `.tsx` under `src/**`. Triggers on `createStaticStyles`, `createStyles`, `cssVar`, `antd-style`, `Flexbox`, `Center`, `Select`, `Modal`, `Drawer`, `Button`, `Tooltip`, `DropdownMenu`, `ContextMenu`, `Popover`, `Switch`, `ScrollArea`, `Toast`, `FloatingSheet`, `Link`, `useNavigate`, `react-router-dom`, `next/link`, `desktopRouter`, `componentMap.desktop`, `.desktop.tsx`, `base-ui`, `@lobehub/ui/base-ui`, 'new component', 'new page', 'edit layout', 'add styles', 'zustand selector', '@lobehub/ui', 'antd import'."
+description: 'LobeHub React component conventions. Use when editing TSX UI, choosing base-ui vs @lobehub/ui vs antd, styling with antd-style, routing, desktop variants, layouts, or component state.'
 user-invocable: false
 ---
 
@@ -53,6 +53,10 @@ For Modal specifically, see the dedicated **modal** skill — use the imperative
 | Layout       | Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow                             |
 | Navigation   | Burger, Menu, SideNav, Tabs                                                           |
 
+## State
+
+When a feature component manages more than 3 pieces of state (`useState`/`useReducer`/derived state), extract the logic into a custom hook (e.g. `useXxx`). Keep the component focused on rendering — the hook holds state and handlers, so logic can be unit-tested without rendering the component.
+
 ## Layout
 
 Use `Flexbox` and `Center` from `@lobehub/ui`. See `references/layout-kit.md` for full props and examples.

.agents/skills/response-compliance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: response-compliance
-description: OpenResponses API compliance testing. Use when testing the Response API endpoint, running compliance tests, or debugging Response API schema issues. Triggers on 'compliance', 'response api test', 'openresponses test'.
+description: 'OpenResponses API compliance testing. Use for Response API endpoint tests, compliance runs, schema debugging, response api test, or openresponses test tasks.'
 ---
 
 # OpenResponses Compliance Test

.agents/skills/review-checklist/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-checklist
-description: "Common recurring mistakes in LobeHub code review — `console.*` leftovers, missing `return await`, hardcoded secrets, hardcoded i18n strings, desktop router pair drift, antd vs `@lobehub/ui`, non-idempotent migrations, cloud impact red flags. Use as a quick checklist when reviewing a PR, diff, or branch change. Triggers on 'code review', 'review the diff', 'review this PR', 'review changes', 'PR review checklist', '审一下', '审 PR'."
+description: 'LobeHub code review checklist. Use when reviewing a PR, diff, or branch for console leftovers, return await, secrets, i18n, desktop router drift, UI imports, migrations, or cloud impact.'
 user-invocable: false
 ---
 

.agents/skills/skills-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skills-audit
-description: Weekly audit of `.agents/skills/*/SKILL.md` — surfaces duplicate / overlapping / stale skills, inconsistent descriptions, broken cross-references, and merge/delete candidates. Run as a recurring health-check, not during normal feature work.
+description: 'Audit .agents/skills SKILL.md files. Use for recurring checks of duplicate, overlapping, stale, inconsistent, or broken skills and merge/delete candidates.'
 disable-model-invocation: true
 argument-hint: '[--verbose | --apply]'
 ---

.agents/skills/spa-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spa-routes
-description: "SPA roots-vs-features split for LobeHub — thin route segments under `src/routes/` delegate to domain components under `src/features/`. Use when editing `src/routes/` segments, `src/spa/router/desktopRouter.config.tsx` or `desktopRouter.config.desktop.tsx` (MUST update both together — `desktopRouter.sync.test.tsx` enforces this), `mobileRouter.config.tsx`, `popupRouter.config.tsx`, or moving UI/logic between `routes/` and `features/`. Triggers on `desktopRouter.config`, `mobileRouter.config`, `popupRouter.config`, `src/routes/**`, `src/features/**`, 'add a route', 'new page', 'route segment', '路由'."
+description: 'LobeHub SPA route architecture. Use when editing src/routes, src/features delegation, desktop/mobile/popup router configs, .desktop variants, route segments, redirects, or new pages.'
 user-invocable: false
 ---
 
@@ -94,6 +94,27 @@ Anything that changes the tree (new segment, renamed `path`, moved layout, new c
 
 ---
 
+## 3b. Other `.desktop.{ts,tsx}` variants inside `src/routes/`
+
+The router pair is **not** the only `.desktop` variant pattern in this repo. Some route trees colocate a `<name>.desktop.{ts,tsx}` next to its base `<name>.{ts,tsx}` — Vite's resolver swaps in the `.desktop` file for Electron builds. Same drift risk as the router pair: editing only one side can break Electron silently.
+
+Known variants today:
+
+| Base file (web)                                       | Desktop file (Electron)                                       | Purpose                                                                                                                                    |
+| ----------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src/routes/(main)/settings/features/componentMap.ts` | `src/routes/(main)/settings/features/componentMap.desktop.ts` | Settings tab → component map. Web uses dynamic `import()`; desktop uses sync imports. `componentMap.sync.test.ts` enforces identical keys. |
+| `src/routes/(main)/agent/index.tsx`                   | `src/routes/(main)/agent/index.desktop.tsx`                   | Page entry. Desktop variant overrides the web page wholesale (e.g. extra popup guards).                                                    |
+| `src/routes/(main)/group/index.tsx`                   | `src/routes/(main)/group/index.desktop.tsx`                   | Same pattern as agent.                                                                                                                     |
+
+**Rules:**
+
+1. After editing **any** `.ts`/`.tsx` under `src/routes/`, glob the same directory for a `<filename>.desktop.{ts,tsx}` sibling. If one exists, apply the equivalent change there in the same commit.
+2. When adding a new SettingsTab, register it in **both** `componentMap.ts` (with `dynamic(...)`) and `componentMap.desktop.ts` (with a sync `import`). `componentMap.sync.test.ts` will fail the build otherwise.
+3. When adding a new desktop-only page wholesale-override, prefer a single base file with platform-aware code over introducing a new `.desktop.tsx` variant — only add a new variant when the two trees genuinely diverge (different store wiring, different popup guards, etc.).
+4. When deleting, remove **both** files together.
+
+---
+
 ## 4. How to Divide Files (route vs feature)
 
 | Question                                                 | Put in `src/routes/`                                     | Put in `src/features/`       |

.agents/skills/store-data-structures/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: store-data-structures
-description: "Zustand store data-shape patterns for LobeHub — List vs Detail split, Map + Reducer, type definitions sourced from `@lobechat/types` (not `@lobechat/database`). Use when designing store state, choosing between Array (list) and `Record<string, Detail>` (detail map), or implementing a list/detail page pair. Triggers on `messagesMap`, `topicsMap`, `Record<string, Detail>`, 'list vs detail', 'store data shape', 'normalize state', 'state structure'."
+description: 'LobeHub Zustand store data-shape patterns. Use when designing store state, list/detail splits, normalized maps, reducers, messagesMap, topicsMap, or choosing shared type sources.'
 user-invocable: false
 ---
 

.agents/skills/testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: Testing guide using Vitest. Use when writing tests (.test.ts, .test.tsx), fixing failing tests, improving test coverage, or debugging test issues. Triggers on test creation, test debugging, mock setup, or test-related questions.
+description: 'Vitest testing guide. Use when writing or updating tests, fixing failing tests, improving coverage, debugging test issues, or setting up mocks.'
 user-invocable: false
 ---
 

.agents/skills/trpc-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trpc-router
-description: TRPC router development guide. Use when creating or modifying TRPC routers (src/server/routers/**), adding procedures, or working with server-side API endpoints. Triggers on TRPC router creation, procedure implementation, or API endpoint tasks.
+description: 'TRPC router development guide. Use when creating or modifying src/server/routers, adding procedures, or implementing server-side API endpoints.'
 user-invocable: false
 ---
 

.agents/skills/typescript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typescript
-description: "TypeScript code style and type-safety guide for LobeHub. Read before writing or editing any `.ts` / `.tsx` / `.mts` — covers `interface` vs `type`, `Record<PropertyKey, unknown>` over `any`/`object`, `as const satisfies`, `@ts-expect-error` over `@ts-ignore`, `import type` (`separate-type-imports`), `async`/`await` + `Promise.all`, `for…of` over indexed `for`, and the no-silent-`.catch(() => fallback)` rule. Also use when reviewing type quality, deciding module augmentation (`declare module`) over `namespace`, or designing extensible types (e.g. `PipelineContext.metadata`). Triggers on any TypeScript file edit, 'fix the type', 'why is this `any`', 'should this be interface or type', 'eslint type-import', 'ts-expect-error'."
+description: 'LobeHub TypeScript style and type-safety guide. Use when editing TS/TSX/MTS, fixing types, choosing interface vs type, avoiding any/object, import type, async flow, or ts-expect-error.'
 user-invocable: false
 ---
 

.agents/skills/upstash-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upstash-workflow
-description: "Upstash Workflow + QStash implementation guide for LobeHub — 3-layer architecture (process → paginate → execute), fan-out patterns. Use when creating an async workflow, implementing fan-out (paginate → execute), or wiring `serve()` + `context.run` / `context.call` steps. Triggers on `serve()`, `context.run`, `context.call`, `context.sleep`, `qstash`, 'async workflow', 'fan-out workflow', 'QStash workflow'."
+description: 'LobeHub Upstash Workflow and QStash guide. Use for async workflows, process/paginate/execute fan-out, serve handlers, context.run/call/sleep, or workflow triggers.'
 user-invocable: false
 ---
 

.agents/skills/zustand/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zustand
-description: "LobeHub Zustand store conventions: public/internal/dispatch action layers, optimistic update pattern, slice composition via `flattenActions`, and class-based action migration. Use whenever working under `src/store/**`, adding a `createXxxSlice`, writing `internal_*` or `internal_dispatch*` actions, designing `messagesMap`/`topicsMap` reducers, refactoring a `StateCreator` object slice into a `XxxActionImpl` class, or debugging stale store reads. Triggers on `useChatStore`/`useUserStore`/`useGlobalStore`, `createStore`, `flattenActions`, `StoreSetter`, `internal_dispatch`, 'add an action', 'zustand selector', 'store slice', 'class action', 'optimistic update'."
+description: 'LobeHub Zustand store conventions. Use when editing src/store, store slices, public/internal actions, dispatch actions, flattenActions, optimistic updates, selectors, maps, or class action migration.'
 user-invocable: false
 ---
 
@@ -177,29 +177,12 @@ export const chatGroupAction: StateCreator<
 
 ### Slices That Don't Currently Need `set`
 
-When a slice doesn't write local state at the moment — e.g. it reads context
-from `#get()` and forwards calls to another store, or just runs hooks — drop
-the `#set` field. Otherwise ESLint's `no-unused-vars` flags the unused private
-field.
-
-Mark the constructor's `set` param as `_set` and `void _set` it to keep the
-`(set, get, api)` shape aligned with `StateCreator`. This is **a snapshot of
-the current need, not a permanent contract** — if a later change needs `set`,
-restore the `#set` field and use it; do not invent a workaround to keep the
-"unused" form.
+When a slice doesn't write local state (e.g. it delegates to another store or just runs hooks), drop `#set` and mark the constructor param as `_set` with `void _set` to keep the `(set, get, api)` shape:
 
 ```ts
-type Setter = StoreSetter<ConversationStore>;
-
-export const toolSlice = (set: Setter, get: () => ConversationStore, _api?: unknown) =>
-  new ToolActionImpl(set, get, _api);
-
 export class ToolActionImpl {
   readonly #get: () => ConversationStore;
 
-  // Mark unused params with `_` prefix and `void _x` so the constructor still
-  // matches StateCreator's `(set, get, api)` shape without triggering unused
-  // diagnostics.
   constructor(_set: Setter, get: () => ConversationStore, _api?: unknown) {
     void _set;
     void _api;
@@ -212,27 +195,8 @@ export class ToolActionImpl {
     hooks.onToolCallComplete?.(id, undefined);
   };
 }
-
-export type ToolAction = Pick<ToolActionImpl, keyof ToolActionImpl>;
 ```
 
-Rules of thumb:
-
-- If a slice doesn't currently call `set`, drop `#set` (use `_set` + `void _set`
-  in the constructor). When a later edit needs `set`, restore `#set` and use it.
-- Don't add `setNamespace` for slices that don't write state. Add it when the
-  slice starts writing state.
-- Never leave `#set` declared but unused "for future use" — lint will fail and
-  re-adding it later costs nothing.
-
-### Do / Don't
-
-- **Do**: keep constructor signature aligned with `StateCreator` params `(set, get, api)`.
-- **Do**: use `#private` to avoid `set/get` being exposed.
-- **Do**: use `flattenActions` instead of spreading class instances.
-- **Do**: drop `#set` (and use `_set` + `void _set` in the constructor) for
-  delegate-only slices that never write state — keeps lint green without
-  breaking the `(set, get, api)` shape.
-- **Don't**: keep both old slice objects and class actions active at the same time.
-- **Don't**: keep an unused `#set` field "for future use" — it fails ESLint and
-  re-adding it later costs nothing.
+- Drop `#set` when unused; restore it when a later edit needs `set` — re-adding costs nothing.
+- Don't add `setNamespace` for slices that don't write state.
+- Don't keep both old slice objects and class actions active at the same time during migration.

.cursorindexingignore

@@ -1,6 +1,7 @@
 # Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)
+
 locales/
 apps/desktop/resources/locales/
 **/__snapshots__/
 **/fixtures/
-src/database/migrations/
+packages/database/migrations/

.env.example

@@ -223,6 +223,29 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # The LobeChat agents market index url
 # AGENTS_INDEX_URL=https://chat-agents.lobehub.com
 
+# #######################################
+# ######### Cloud Sandbox Service #######
+# #######################################
+
+# Sandbox provider for built-in code execution, shell, file operations, and export.
+# Supported values: market, onlyboxes
+# SANDBOX_PROVIDER=market
+
+# Required when SANDBOX_PROVIDER=onlyboxes. Base URL of the Onlyboxes console API, without /api/v1.
+# ONLYBOXES_BASE_URL=https://onlyboxes.example.com
+
+# Required when SANDBOX_PROVIDER=onlyboxes. Must match Onlyboxes CONSOLE_JIT_SIGNING_KEY.
+# ONLYBOXES_JIT_SIGNING_KEY=onlyboxes-jit-signing-secret
+
+# Optional JIT token issuer. Defaults to APP_URL.
+# ONLYBOXES_JIT_ISSUER=https://lobehub.example.com
+
+# Optional JIT token TTL in seconds.
+# ONLYBOXES_JIT_TTL_SEC=1800
+
+# Optional terminal session lease in seconds for the Onlyboxes provider.
+# ONLYBOXES_LEASE_TTL_SEC=900
+
 # #######################################
 # ########### Plugin Service ############
 # #######################################
@@ -376,6 +399,11 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # Postgres database URL
 # DATABASE_URL=postgres://username:password@host:port/database
 
+# Optional: server-side timeout (in milliseconds) for a single SQL statement.
+# When set, Postgres aborts any statement/idle transaction exceeding it, so a stuck
+# query can't block indefinitely. Leave unset to keep Postgres' default of no timeout.
+# DATABASE_STATEMENT_TIMEOUT=300000
+
 # use `openssl rand -base64 32` to generate a key for the encryption of the database
 # we use this key to encrypt the user api key and proxy url
 # KEY_VAULTS_SECRET=xxxxx/xxxxxxxxxxxxxx=

.github/actions/desktop-publish-s3/action.yml

@@ -75,7 +75,7 @@ runs:
 
         # 1. 上传安装包到版本目录
         echo "📦 Uploading release files to s3://$S3_BUCKET/$CHANNEL/$VERSION/"
-        for file in release/*.dmg release/*.zip release/*.exe release/*.AppImage release/*.deb release/*.rpm release/*.snap release/*.tar.gz; do
+        for file in release/*.dmg release/*.zip release/*.exe release/*.AppImage release/*.deb release/*.rpm release/*.snap release/*.tar.gz release/*.blockmap; do
           if [ -f "$file" ]; then
             filename=$(basename "$file")
             echo "   ↗️ $filename"

.github/workflows/test.yml

@@ -32,7 +32,7 @@ jobs:
     runs-on: ubuntu-latest
     name: Test Packages
     env:
-      PACKAGES: '@lobechat/file-loaders @lobechat/prompts @lobechat/model-runtime @lobechat/web-crawler @lobechat/electron-server-ipc @lobechat/utils @lobechat/python-interpreter @lobechat/context-engine @lobechat/agent-runtime @lobechat/conversation-flow @lobechat/ssrf-safe-fetch @lobechat/memory-user-memory @lobechat/types @lobechat/builtin-tool-lobe-agent model-bank'
+      PACKAGES: '@lobechat/file-loaders @lobechat/prompts @lobechat/model-runtime @lobechat/web-crawler @lobechat/electron-server-ipc @lobechat/utils @lobechat/python-interpreter @lobechat/context-engine @lobechat/agent-runtime @lobechat/conversation-flow @lobechat/ssrf-safe-fetch @lobechat/memory-user-memory @lobechat/types @lobechat/builtin-tool-lobe-agent model-bank @lobechat/agent-gateway-client @lobechat/agent-manager-runtime @lobechat/device-gateway-client @lobechat/device-identity @lobechat/eval-dataset-parser @lobechat/eval-rubric @lobechat/fetch-sse @lobechat/heterogeneous-agents'
 
     steps:
       - name: Checkout

AGENTS.md

@@ -115,14 +115,23 @@ cd packages/database && bunx vitest run --silent='passed-only' '[file]'
 ```
 
 - Prefer `vi.spyOn` over `vi.mock`
-- Tests must pass type check: `bun run type-check`
-- After 2 failed fix attempts, stop and ask for help
+
+### Type Checking
+
+```bash
+bun run type-check
+```
 
 ### i18n
 
 - Add keys to a namespace file under `src/locales/default/` (e.g. `agent.ts`, `auth.ts`)
-- For dev preview: translate `locales/zh-CN/` and `locales/en-US/`
-- `pnpm i18n` is slow; run it manually when locale keys need updating (e.g. before opening a PR).
+- Ship en-US and zh-CN by hand in the same PR: write the English source in `src/locales/default/*.ts` and mirror it to `locales/en-US/`; hand-translate `locales/zh-CN/`. Leave all other locales to CI.
+- Don't run `pnpm i18n` manually by default — a daily CI workflow (`auto-i18n.yml`) runs it and opens an automated translation PR for any missing keys.
+- Run `pnpm i18n` manually only when your branch needs the translated locales immediately, instead of waiting for the daily job (slow; requires `OPENAI_API_KEY`). Note it only fills keys missing from other locales — value-only edits never need it.
+
+### Code Style
+
+- When a single file grows beyond \~800 lines, consider splitting it into multiple files (extract sub-components, hooks, helpers, or types). Smaller, focused files are friendly to humans and agents.
 
 ### Code Review
 

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 # Changelog
 
+## [Version 2.2.1](https://github.com/lobehub/lobe-chat/compare/v0.0.0-nightly.pr15228.13999...v2.2.1)
+
+<sup>Released on **2026-05-29**</sup>
+
+#### ✨ Features
+
+- **device**: device registry TRPC (register / list / update / remove).
+- **bot**: add iMessage Desktop setup and bridge.
+- **desktop**: show zoom level HUD on Cmd+/- and Cmd+0.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **device**: device registry TRPC (register / list / update / remove), closes [#15299](https://github.com/lobehub/lobe-chat/issues/15299) ([671b252](https://github.com/lobehub/lobe-chat/commit/671b252))
+- **bot**: add iMessage Desktop setup and bridge, closes [#15228](https://github.com/lobehub/lobe-chat/issues/15228) ([6d94635](https://github.com/lobehub/lobe-chat/commit/6d94635))
+- **desktop**: show zoom level HUD on Cmd+/- and Cmd+0, closes [#15294](https://github.com/lobehub/lobe-chat/issues/15294) ([109545c](https://github.com/lobehub/lobe-chat/commit/109545c))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 2.2.0](https://github.com/lobehub/lobe-chat/compare/v2.1.59-canary.27...v2.2.0)
 
 <sup>Released on **2026-05-18**</sup>

Dockerfile

@@ -210,6 +210,14 @@ ENV NEXT_PUBLIC_S3_DOMAIN="" \
     S3_ENABLE_PATH_STYLE="" \
     S3_SET_ACL=""
 
+# Cloud Sandbox
+ENV SANDBOX_PROVIDER="" \
+    ONLYBOXES_BASE_URL="" \
+    ONLYBOXES_JIT_ISSUER="" \
+    ONLYBOXES_JIT_SIGNING_KEY="" \
+    ONLYBOXES_JIT_TTL_SEC="" \
+    ONLYBOXES_LEASE_TTL_SEC=""
+
 # Model Variables
 ENV \
     # AI21

apps/cli/e2e/agent-signal.e2e.test.ts

@@ -0,0 +1,88 @@
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  assertGoldenFinalState,
+  extractGoldenOutcomes,
+} from './fixtures/agent-signal/assertGoldenFinalState';
+
+/**
+ * E2E tests for `lh agent-signal trigger`.
+ *
+ * The "golden fixture" block runs fully offline — it is the structural
+ * regression baseline that the execAgent migration asserts
+ * against. The "live trigger" block requires a running server + authenticated
+ * CLI and is gated behind AGENT_SIGNAL_AGENT_ID (or AGENT_ID).
+ *
+ * Prerequisites for the live block:
+ * - `lh` (or LH_CLI_PATH) points at the built CLI
+ * - User is authenticated (`lh login`) against a dev server with Agent Signal enabled
+ * - AGENT_SIGNAL_AGENT_ID=<agentId> identifies a target agent the user owns
+ */
+
+const CLI = process.env.LH_CLI_PATH || 'lh';
+const AGENT_ID = process.env.AGENT_SIGNAL_AGENT_ID || process.env.AGENT_ID;
+const TIMEOUT = 60_000;
+
+const goldenPath = fileURLToPath(
+  new URL('./fixtures/agent-signal/nightly-review.golden.json', import.meta.url),
+);
+const golden = JSON.parse(readFileSync(goldenPath, 'utf-8'));
+
+function run(args: string): string {
+  return execSync(`${CLI} ${args}`, {
+    encoding: 'utf-8',
+    env: { ...process.env, PATH: `${process.env.HOME}/.bun/bin:${process.env.PATH}` },
+    timeout: TIMEOUT,
+  }).trim();
+}
+
+describe('agent-signal golden fixture - structural regression', () => {
+  it('captures a recognizable nightly-review source payload', () => {
+    expect(golden.source.sourceType).toBe('agent.nightly_review.requested');
+    expect(golden.source.payload.agentId).toBeTruthy();
+    expect(golden.source.payload.userId).toBeTruthy();
+    expect(golden.source.scopeKey).toContain('agent:');
+  });
+
+  it('extracts ideas / write outcomes / brief from finalState', () => {
+    const outcomes = extractGoldenOutcomes(golden.finalState);
+
+    expect(outcomes.ideas.length).toBeGreaterThanOrEqual(1);
+    expect(outcomes.writeOutcomes.length).toBeGreaterThanOrEqual(1);
+    expect(outcomes.brief).toBeDefined();
+  });
+
+  it('passes the shared structural assertion', () => {
+    expect(() => assertGoldenFinalState(golden.finalState)).not.toThrow();
+  });
+
+  it('rejects an empty finalState', () => {
+    expect(() => assertGoldenFinalState({ messages: [] })).toThrow(/artifact/i);
+  });
+});
+
+describe.skipIf(!AGENT_ID)('lh agent-signal trigger - live', () => {
+  it('triggers a nightly review and returns a workflow run id', () => {
+    const output = run(
+      `agent-signal trigger --source-type agent.nightly_review.requested --agent ${AGENT_ID} --json`,
+    );
+    const result = JSON.parse(output);
+    expect(result).toHaveProperty('accepted');
+    expect(result).toHaveProperty('scopeKey');
+    // When Agent Signal is enabled for the account, a workflow run id is returned.
+    if (result.accepted) {
+      expect(typeof result.workflowRunId).toBe('string');
+      expect(result.workflowRunId.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('exits non-zero on an invalid source type', () => {
+    expect(() =>
+      run(`agent-signal trigger --source-type not.a.real.type --agent ${AGENT_ID}`),
+    ).toThrow();
+  });
+});

apps/cli/e2e/fixtures/agent-signal/assertGoldenFinalState.ts

@@ -0,0 +1,127 @@
+/**
+ * Standalone structural assertions for self-iteration finalState snapshots.
+ *
+ * Dependency-free on purpose: the execAgent migration PRs
+ * import this from server tests AND the CLI e2e suite, so it must not pull in
+ * vitest or any server-only module. Mirrors the `kind` discrimination used by
+ * `src/server/services/agentSignal/services/selfIteration/finalStateExtractor.ts`.
+ */
+
+export type ToolResultKind = 'artifact' | 'mutation' | 'read';
+
+export interface ToolResultWithKind {
+  apiName?: string;
+  data: Record<string, unknown> | unknown;
+  kind: ToolResultKind;
+  toolCallId?: string;
+}
+
+export interface GoldenOutcomes {
+  /** The single brief mutation, if any (apiName matches /brief/i). */
+  brief?: ToolResultWithKind;
+  /** Artifact tool results whose apiName mentions an idea. */
+  ideas: ToolResultWithKind[];
+  /** Artifact tool results whose apiName mentions an intent. */
+  intents: ToolResultWithKind[];
+  /** Durable mutation tool results, excluding the brief. */
+  writeOutcomes: ToolResultWithKind[];
+}
+
+interface FinalStateLike {
+  messages?: unknown[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const parseContent = (content: unknown): unknown => {
+  if (typeof content !== 'string') return content;
+  try {
+    return JSON.parse(content);
+  } catch {
+    return content;
+  }
+};
+
+/** Extract every tool result of `kind` from a finalState, in message order. */
+export const extractFromFinalState = (
+  finalState: FinalStateLike,
+  kind: ToolResultKind,
+): ToolResultWithKind[] => {
+  const results: ToolResultWithKind[] = [];
+
+  for (const message of finalState.messages ?? []) {
+    if (!isRecord(message)) continue;
+    if (message.role !== 'tool') continue;
+
+    const content = parseContent(message.content);
+    const contentRecord = isRecord(content) ? content : undefined;
+    const pluginState = isRecord(message.pluginState) ? message.pluginState : undefined;
+    const resultKind = contentRecord?.kind ?? pluginState?.kind;
+
+    if (resultKind !== kind) continue;
+
+    results.push({
+      apiName: typeof message.apiName === 'string' ? message.apiName : undefined,
+      data: contentRecord ?? content,
+      kind,
+      toolCallId: typeof message.tool_call_id === 'string' ? message.tool_call_id : undefined,
+    });
+  }
+
+  return results;
+};
+
+const matchesApiName = (result: ToolResultWithKind, pattern: RegExp): boolean =>
+  typeof result.apiName === 'string' && pattern.test(result.apiName);
+
+const briefText = (brief?: ToolResultWithKind): string => {
+  if (!brief || !isRecord(brief.data)) return '';
+  const summary = typeof brief.data.summary === 'string' ? brief.data.summary : '';
+  const body = typeof brief.data.body === 'string' ? brief.data.body : '';
+  return `${summary}${body}`.trim();
+};
+
+/** Partition a finalState into ideas / intents / writeOutcomes / brief buckets. */
+export const extractGoldenOutcomes = (finalState: FinalStateLike): GoldenOutcomes => {
+  const artifacts = extractFromFinalState(finalState, 'artifact');
+  const mutations = extractFromFinalState(finalState, 'mutation');
+
+  const brief = mutations.find((m) => matchesApiName(m, /brief/i));
+
+  return {
+    brief,
+    ideas: artifacts.filter((a) => matchesApiName(a, /idea/i)),
+    intents: artifacts.filter((a) => matchesApiName(a, /intent/i)),
+    writeOutcomes: mutations.filter((m) => !matchesApiName(m, /brief/i)),
+  };
+};
+
+/**
+ * Structural regression assertion for a self-iteration finalState.
+ *
+ * Throws (with a descriptive message) when the run produced no structured
+ * output: it requires at least one artifact (idea or intent), at least one
+ * durable write outcome, and a non-empty brief. Never compares text verbatim.
+ */
+export const assertGoldenFinalState = (finalState: FinalStateLike): GoldenOutcomes => {
+  const outcomes = extractGoldenOutcomes(finalState);
+  const artifactCount = outcomes.ideas.length + outcomes.intents.length;
+
+  if (artifactCount < 1) {
+    throw new Error(`Expected >= 1 artifact (idea/intent) in finalState, found ${artifactCount}`);
+  }
+
+  if (outcomes.writeOutcomes.length < 1) {
+    throw new Error(
+      `Expected >= 1 write outcome (mutation) in finalState, found ${outcomes.writeOutcomes.length}`,
+    );
+  }
+
+  const text = briefText(outcomes.brief);
+  if (text.length === 0) {
+    throw new Error('Expected a non-empty brief in finalState, found none');
+  }
+
+  return outcomes;
+};

apps/cli/e2e/fixtures/agent-signal/nightly-review.golden.json

@@ -0,0 +1,61 @@
+{
+  "description": "Desensitized golden snapshot of one nightly-review self-iteration run. Used as a structural regression baseline by the execAgent migration which converges all agent execution paths (chat, self-iteration, memoryWriter, skillManagement) onto a single execAgent entry point. Assert structure, never byte-for-byte: the LLM output is non-deterministic.",
+  "finalState": {
+    "messages": [
+      {
+        "content": "Run the nightly self-review for the local window.",
+        "role": "user"
+      },
+      {
+        "apiName": "getEvidenceDigest",
+        "content": "{\"kind\":\"read\",\"topicCount\":3,\"messageCount\":42,\"window\":\"2026-05-30/2026-05-31\"}",
+        "role": "tool",
+        "tool_call_id": "call_read_1"
+      },
+      {
+        "apiName": "recordSelfReviewIdea",
+        "content": "{\"kind\":\"artifact\",\"idempotencyKey\":\"idea:pref:tone\",\"title\":\"Prefer concise replies\",\"rationale\":\"User repeatedly asked to shorten answers in topic tpc_demo\",\"risk\":\"low\"}",
+        "role": "tool",
+        "tool_call_id": "call_idea_1"
+      },
+      {
+        "apiName": "recordSelfReviewIdea",
+        "content": "{\"kind\":\"artifact\",\"idempotencyKey\":\"idea:skill:drizzle\",\"title\":\"Document Drizzle join helper\",\"rationale\":\"Recurring question about leftJoin usage\",\"risk\":\"medium\"}",
+        "role": "tool",
+        "tool_call_id": "call_idea_2"
+      },
+      {
+        "apiName": "writeMemory",
+        "content": "{\"kind\":\"mutation\",\"status\":\"applied\",\"resourceId\":\"mem_001\",\"summary\":\"Stored tone preference: prefer concise replies\"}",
+        "pluginState": { "kind": "mutation" },
+        "role": "tool",
+        "tool_call_id": "call_mut_1"
+      },
+      {
+        "apiName": "createSelfReviewBrief",
+        "content": "{\"kind\":\"mutation\",\"briefId\":\"brief_001\",\"summary\":\"Nightly review captured 2 ideas and wrote 1 memory.\",\"body\":\"## Highlights\\n- Prefer concise replies\\n- Document Drizzle join helper\"}",
+        "role": "tool",
+        "tool_call_id": "call_brief_1"
+      },
+      {
+        "content": "Nightly review complete. Captured 2 ideas and wrote 1 memory.",
+        "role": "assistant"
+      }
+    ]
+  },
+  "source": {
+    "payload": {
+      "agentId": "agent_demo",
+      "localDate": "2026-05-30",
+      "requestedAt": "2026-05-31T04:00:00.000Z",
+      "reviewWindowEnd": "2026-05-31T04:00:00.000Z",
+      "reviewWindowStart": "2026-05-30T04:00:00.000Z",
+      "timezone": "UTC",
+      "userId": "user_demo"
+    },
+    "scopeKey": "agent:agent_demo:user:user_demo",
+    "sourceId": "nightly-review:user_demo:agent_demo:2026-05-30",
+    "sourceType": "agent.nightly_review.requested",
+    "timestamp": 1748664000000
+  }
+}

apps/cli/man/man1/lh.1

@@ -1,6 +1,6 @@
 .\" Code generated by `npm run man:generate`; DO NOT EDIT.
 .\" Manual command details come from the Commander command tree.
-.TH LH 1 "" "@lobehub/cli 0.0.22" "User Commands"
+.TH LH 1 "" "@lobehub/cli 0.0.24" "User Commands"
 .SH NAME
 lh \- LobeHub CLI \- manage and connect to LobeHub services
 .SH SYNOPSIS
@@ -65,6 +65,9 @@ Manage agents
 .B agent\-group
 Manage agent groups
 .TP
+.B agent\-signal
+Inspect and trigger Agent Signal source events
+.TP
 .B bot
 Manage bot integrations
 .TP

apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/cli",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "type": "module",
   "bin": {
     "lh": "./dist/index.js",
@@ -30,8 +30,10 @@
   "devDependencies": {
     "@lobechat/agent-gateway-client": "workspace:*",
     "@lobechat/device-gateway-client": "workspace:*",
+    "@lobechat/device-identity": "workspace:*",
     "@lobechat/heterogeneous-agents": "workspace:*",
     "@lobechat/local-file-shell": "workspace:*",
+    "@lobechat/tool-runtime": "workspace:*",
     "@trpc/client": "^11.8.1",
     "@types/node": "^22.13.5",
     "@types/ws": "^8.18.1",

apps/cli/pnpm-workspace.yaml

@@ -1,8 +1,12 @@
 packages:
   - '../../packages/agent-gateway-client'
   - '../../packages/device-gateway-client'
+  - '../../packages/device-identity'
   - '../../packages/heterogeneous-agents'
   - '../../packages/local-file-shell'
+  - '../../packages/tool-runtime'
+  - '../../packages/prompts'
+  - '../../packages/const'
   - '../../packages/types'
   - '../../packages/model-bank'
   - '../../packages/business/const'

apps/cli/src/api/client.ts

@@ -70,6 +70,26 @@ export async function getTrpcClient(): Promise<TrpcClient> {
   return _client;
 }
 
+/**
+ * Build a Lambda tRPC client from an already-resolved auth context, without
+ * re-running credential discovery. Use this when the caller already holds a
+ * token (e.g. `lh connect --token <jwt>`) — `getTrpcClient` would re-resolve
+ * via env/stored creds and `process.exit(1)` when none exist, which would
+ * abort an otherwise-valid explicit-token session.
+ */
+export function createLambdaClient(auth: {
+  serverUrl: string;
+  token: string;
+  tokenType: 'apiKey' | 'jwt' | 'serviceToken';
+}): TrpcClient {
+  const headers =
+    auth.tokenType === 'apiKey' ? { 'X-API-Key': auth.token } : { 'Oidc-Auth': auth.token };
+
+  return createTRPCClient<LambdaRouter>({
+    links: [httpLink({ headers, transformer: superjson, url: `${auth.serverUrl}/trpc/lambda` })],
+  });
+}
+
 export async function getToolsTrpcClient(): Promise<ToolsTrpcClient> {
   if (_toolsClient) return _toolsClient;
 

apps/cli/src/auth/apiKey.ts

@@ -13,7 +13,7 @@ interface CurrentUserResponse {
 export async function getUserIdFromApiKey(apiKey: string, serverUrl?: string): Promise<string> {
   const normalizedServerUrl = normalizeUrl(serverUrl) || resolveServerUrl();
 
-  const response = await fetch(`${normalizedServerUrl}/api/v1/users/me`, {
+  const response = await fetch(`${normalizedServerUrl}/api/v1/users/me?includeCount=0`, {
     headers: {
       Authorization: `Bearer ${apiKey}`,
     },
@@ -23,7 +23,9 @@ export async function getUserIdFromApiKey(apiKey: string, serverUrl?: string): P
   try {
     body = (await response.json()) as CurrentUserResponse;
   } catch {
-    throw new Error(`Failed to parse response from ${normalizedServerUrl}/api/v1/users/me.`);
+    throw new Error(
+      `Failed to parse response from ${normalizedServerUrl}/api/v1/users/me?includeCount=0.`,
+    );
   }
 
   if (!response.ok || body?.success === false) {

apps/cli/src/auth/resolveToken.ts

@@ -20,7 +20,7 @@ interface ResolvedAuth {
 /**
  * Parse the `sub` claim from a JWT without verifying the signature.
  */
-function parseJwtSub(token: string): string | undefined {
+export function parseJwtSub(token: string): string | undefined {
   try {
     const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString());
     return payload.sub;

apps/cli/src/commands/agent-signal/index.ts

@@ -0,0 +1,129 @@
+import type { Command } from 'commander';
+import pc from 'picocolors';
+
+import { getTrpcClient } from '../../api/client';
+import { log } from '../../utils/logger';
+
+/**
+ * Producer source types a developer may trigger manually for local testing.
+ * Mirrors `AGENT_SIGNAL_TRIGGER_SOURCE_TYPES` on the server; kept inline so the
+ * CLI bundle does not pull in server-only modules.
+ */
+const TRIGGER_SOURCE_TYPES = [
+  'agent.nightly_review.requested',
+  'agent.self_reflection.requested',
+  'agent.self_feedback_intent.declared',
+  'agent.user.message',
+  'tool.outcome.completed',
+  'tool.outcome.failed',
+] as const;
+
+type TriggerSourceType = (typeof TRIGGER_SOURCE_TYPES)[number];
+
+export function registerAgentSignalCommand(program: Command) {
+  const agentSignal = program
+    .command('agent-signal')
+    .description('Inspect and trigger Agent Signal source events');
+
+  agentSignal
+    .command('trigger')
+    .description('Trigger an Agent Signal source event for the authenticated user')
+    .requiredOption(
+      '--source-type <type>',
+      `Source type to emit. One of:\n  ${TRIGGER_SOURCE_TYPES.join('\n  ')}`,
+    )
+    .option('--agent <agentId>', 'Target agent ID (required for agent-scoped source types)')
+    .option('--topic <topicId>', 'Topic ID to scope the event to')
+    .option('--payload-json <json>', 'JSON object shallow-merged over the default payload')
+    .option('--source-id <id>', 'Override the auto-derived dedupe source id')
+    .option('--scope-key <key>', 'Override the auto-derived scope key')
+    .option('--timestamp <ms>', 'Event timestamp in milliseconds')
+    .option('--json', 'Output JSON')
+    .action(
+      async (options: {
+        agent?: string;
+        json?: boolean;
+        payloadJson?: string;
+        scopeKey?: string;
+        sourceId?: string;
+        sourceType: string;
+        timestamp?: string;
+        topic?: string;
+      }) => {
+        const sourceType = options.sourceType as TriggerSourceType;
+
+        if (!TRIGGER_SOURCE_TYPES.includes(sourceType)) {
+          console.error(
+            `${pc.red('✗')} Invalid --source-type "${options.sourceType}". Expected one of: ${TRIGGER_SOURCE_TYPES.join(', ')}`,
+          );
+          process.exit(1);
+          return;
+        }
+
+        let payloadOverride: Record<string, unknown> | undefined;
+        if (options.payloadJson) {
+          try {
+            const parsed = JSON.parse(options.payloadJson);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+              throw new Error('payload must be a JSON object');
+            }
+            payloadOverride = parsed as Record<string, unknown>;
+          } catch (error: any) {
+            console.error(`${pc.red('✗')} Failed to parse --payload-json: ${error.message}`);
+            process.exit(1);
+            return;
+          }
+        }
+
+        let timestamp: number | undefined;
+        if (options.timestamp !== undefined) {
+          timestamp = Number(options.timestamp);
+          if (!Number.isFinite(timestamp)) {
+            console.error(`${pc.red('✗')} --timestamp must be a number (milliseconds)`);
+            process.exit(1);
+            return;
+          }
+        }
+
+        log.debug(
+          'agent-signal trigger: sourceType=%s agent=%s topic=%s',
+          sourceType,
+          options.agent,
+          options.topic,
+        );
+
+        const client = await getTrpcClient();
+
+        try {
+          const result = await client.agentSignal.triggerSourceEvent.mutate({
+            agentId: options.agent,
+            payloadOverride,
+            scopeKey: options.scopeKey,
+            sourceId: options.sourceId,
+            sourceType,
+            timestamp,
+            topicId: options.topic,
+          });
+
+          if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+          }
+
+          if (!result.accepted) {
+            console.log(
+              `${pc.yellow('!')} Agent Signal is disabled for this account — event was not enqueued (scopeKey: ${pc.bold(result.scopeKey)})`,
+            );
+            return;
+          }
+
+          console.log(`${pc.green('✓')} Triggered ${pc.bold(sourceType)}`);
+          console.log(`  Scope key:       ${result.scopeKey}`);
+          console.log(`  Workflow run id: ${result.workflowRunId}`);
+        } catch (error: any) {
+          console.error(`${pc.red('✗')} Failed to trigger source event: ${error.message}`);
+          process.exit(1);
+        }
+      },
+    );
+}

apps/cli/src/commands/agent.ts

@@ -347,22 +347,33 @@ export function registerAgentCommand(program: Command) {
         const { serverUrl, headers, token, tokenType } = await getAgentStreamAuthInfo();
         const agentGatewayUrl = options.sse ? undefined : resolveAgentGatewayUrl();
 
-        if (agentGatewayUrl) {
-          await streamAgentEventsViaWebSocket({
-            gatewayUrl: agentGatewayUrl,
-            json: options.json,
-            operationId,
-            serverUrl,
-            token,
-            tokenType,
-            verbose: options.verbose,
-          });
-        } else {
-          const streamUrl = `${serverUrl}/api/agent/stream?operationId=${encodeURIComponent(operationId)}`;
-          await streamAgentEvents(streamUrl, headers, {
-            json: options.json,
-            verbose: options.verbose,
-          });
+        try {
+          if (agentGatewayUrl) {
+            await streamAgentEventsViaWebSocket({
+              gatewayUrl: agentGatewayUrl,
+              json: options.json,
+              operationId,
+              serverUrl,
+              token,
+              tokenType,
+              verbose: options.verbose,
+            });
+          } else {
+            const streamUrl = `${serverUrl}/api/agent/stream?operationId=${encodeURIComponent(operationId)}`;
+            await streamAgentEvents(streamUrl, headers, {
+              json: options.json,
+              verbose: options.verbose,
+            });
+          }
+        } catch (error) {
+          // The live stream (gateway WS / SSE) dropped before the run finished —
+          // the run is still executing server-side. Instead of failing, fall back
+          // to polling the run status until it reaches a terminal state.
+          if (options.json) throw error;
+          log.warn(
+            `Live stream unavailable (${(error as Error).message}). Polling run status every 10s…`,
+          );
+          await pollAgentRunStatus(client, operationId);
         }
       },
     );
@@ -626,3 +637,56 @@ function colorStatus(status: string): string {
     }
   }
 }
+
+const TERMINAL_RUN_STATUSES = new Set([
+  'completed',
+  'done',
+  'success',
+  'failed',
+  'error',
+  'cancelled',
+  'canceled',
+  'aborted',
+]);
+
+/**
+ * Fallback when the live stream (gateway WebSocket / SSE) drops before the run
+ * finishes: the run is still executing server-side, so poll its status every 10s
+ * until it reaches a terminal state (or is no longer tracked, which also means it
+ * has finished). Avoids hard-exiting on a transient gateway disconnect.
+ */
+async function pollAgentRunStatus(
+  client: Awaited<ReturnType<typeof getTrpcClient>>,
+  operationId: string,
+): Promise<void> {
+  const POLL_MS = 10_000;
+  let lastStatus = '';
+  for (let i = 0; ; i++) {
+    if (i > 0) await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+
+    let r: any;
+    try {
+      r = await client.aiAgent.getOperationStatus.query({ operationId } as any);
+    } catch (error) {
+      log.error(`Status poll failed: ${(error as Error).message}`);
+      process.exit(1);
+    }
+
+    if (!r) {
+      log.info('Run is no longer tracked — finished (or expired).');
+      return;
+    }
+
+    const status = r.status || r.state || 'unknown';
+    if (status !== lastStatus) {
+      lastStatus = status;
+      const steps = r.stepCount !== undefined ? ` · ${r.stepCount} step(s)` : '';
+      log.info(`Run status: ${colorStatus(status)}${steps}`);
+    }
+
+    if (TERMINAL_RUN_STATUSES.has(status)) {
+      if (r.error) log.error(`Run error: ${r.error}`);
+      return;
+    }
+  }
+}

apps/cli/src/commands/connect.test.ts

@@ -15,6 +15,7 @@ vi.mock('../auth/resolveToken', () => ({
   }),
 }));
 vi.mock('../settings', () => ({
+  loadOrCreateConnectionId: vi.fn().mockReturnValue('test-connection-id'),
   loadSettings: vi.fn().mockReturnValue(null),
   normalizeUrl: vi.fn((url?: string) => (url ? url.replace(/\/$/, '') : undefined)),
   saveSettings: vi.fn(),

apps/cli/src/commands/connect.ts

@@ -25,7 +25,8 @@ import {
   stopDaemon,
   writeStatus,
 } from '../daemon/manager';
-import { loadSettings, normalizeUrl, saveSettings } from '../settings';
+import { registerDevice, resolveDeviceIdentity } from '../device/register';
+import { loadOrCreateConnectionId, loadSettings, normalizeUrl, saveSettings } from '../settings';
 import { executeToolCall } from '../tools';
 import { cleanupAllProcesses } from '../tools/shell';
 import { log, setVerbose } from '../utils/logger';
@@ -192,8 +193,19 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
 
   const resolvedGatewayUrl = gatewayUrl || OFFICIAL_GATEWAY_URL;
 
+  // Resolve a stable device identity. An explicit `--device-id` wins (lets a
+  // user pin a VM to a fixed identity); otherwise derive from the machine id so
+  // the same machine + user maps to one device across reconnects.
+  const identity = resolveDeviceIdentity(auth.userId, options.deviceId);
+
+  // Freeform channel label (`cli` by default); `LOBEHUB_CLI_CHANNEL` lets a
+  // dev build tag itself `cli-dev` so the gateway can prioritise / display it.
+  const channel = process.env.LOBEHUB_CLI_CHANNEL || 'cli';
+
   const client = new GatewayClient({
-    deviceId: options.deviceId,
+    channel,
+    connectionId: loadOrCreateConnectionId(),
+    deviceId: identity?.deviceId ?? options.deviceId,
     gatewayUrl: resolvedGatewayUrl,
     logger: isDaemonChild ? createDaemonLogger() : log,
     serverUrl: auth.serverUrl,
@@ -268,6 +280,7 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
       result: {
         content: result.content,
         error: result.error,
+        state: result.state,
         success: result.success,
       },
     });
@@ -386,6 +399,21 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
     process.exit(0);
   });
 
+  // Register this device in the server registry before opening the WS, so the
+  // row exists by the time the gateway reports it online. `lh login` already
+  // registers, but re-running here is cheap (idempotent upsert) and covers
+  // `--token` sessions that never went through login. Best-effort: a failure
+  // must not block the connection.
+  if (identity) {
+    try {
+      // Reuse the already-resolved auth (respects `--token` mode) so we don't
+      // re-discover creds and exit when none are found.
+      await registerDevice(auth, identity);
+    } catch (err) {
+      error(`Device registration failed (non-fatal): ${(err as Error).message}`);
+    }
+  }
+
   // Connect
   await client.connect();
 }

apps/cli/src/commands/login.ts

@@ -6,8 +6,10 @@ import type { Command } from 'commander';
 
 import { getUserIdFromApiKey } from '../auth/apiKey';
 import { saveCredentials } from '../auth/credentials';
+import { parseJwtSub } from '../auth/resolveToken';
 import { CLI_API_KEY_ENV } from '../constants/auth';
 import { OFFICIAL_SERVER_URL } from '../constants/urls';
+import { registerDevice, resolveDeviceIdentity } from '../device/register';
 import { loadSettings, normalizeUrl, saveSettings } from '../settings';
 import { log } from '../utils/logger';
 
@@ -213,6 +215,30 @@ export function registerLoginCommand(program: Command) {
                   },
             );
 
+            // Register this device in the server registry right after auth, so
+            // the device row exists without waiting for a later `lh connect`
+            // (which only adds the channel-online step). Mirrors the desktop
+            // app, which registers on login. Best-effort: a failure here must
+            // not fail the login.
+            //
+            // Skip the `fallback` source: `lh login` has no `--device-id` and
+            // persists no fallback id, so a machine without a readable
+            // machine-id would derive a *fresh random* id on every login —
+            // registering it just spawns orphan device rows that never match
+            // the id a later `lh connect` resolves. Defer registration to
+            // `connect` in that case, where the same id is reused for the WS.
+            const identity = resolveDeviceIdentity(parseJwtSub(body.access_token));
+            if (identity && identity.identitySource !== 'fallback') {
+              try {
+                await registerDevice(
+                  { serverUrl, token: body.access_token, tokenType: 'jwt' },
+                  identity,
+                );
+              } catch (err) {
+                log.warn(`Device registration failed (non-fatal): ${(err as Error).message}`);
+              }
+            }
+
             log.info('Login successful! Credentials saved.');
             return;
           }

apps/cli/src/commands/topic.test.ts

@@ -6,9 +6,13 @@ import { registerTopicCommand } from './topic';
 
 const { mockTrpcClient } = vi.hoisted(() => ({
   mockTrpcClient: {
+    message: {
+      getMessages: { query: vi.fn() },
+    },
     topic: {
       batchDelete: { mutate: vi.fn() },
       createTopic: { mutate: vi.fn() },
+      getTopicDetail: { query: vi.fn() },
       getTopics: { query: vi.fn() },
       recentTopics: { query: vi.fn() },
       removeTopic: { mutate: vi.fn() },
@@ -41,6 +45,18 @@ describe('topic command', () => {
         (fn as ReturnType<typeof vi.fn>).mockReset();
       }
     }
+    for (const method of Object.values(mockTrpcClient.message)) {
+      for (const fn of Object.values(method)) {
+        (fn as ReturnType<typeof vi.fn>).mockReset();
+      }
+    }
+    // Default stub for getTopicDetail
+    mockTrpcClient.topic.getTopicDetail.query.mockResolvedValue({
+      favorite: false,
+      id: 't1',
+      title: 'Test Topic',
+      updatedAt: new Date().toISOString(),
+    });
   });
 
   afterEach(() => {
@@ -203,4 +219,130 @@ describe('topic command', () => {
       expect(mockTrpcClient.topic.recentTopics.query).toHaveBeenCalledWith({ limit: 10 });
     });
   });
+
+  describe('view', () => {
+    it('should display topic metadata and messages', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([
+        { content: 'Hello world', id: 'm1', role: 'user' },
+        { content: 'Hi there', id: 'm2', role: 'assistant' },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1']);
+
+      expect(mockTrpcClient.topic.getTopicDetail.query).toHaveBeenCalledWith(
+        expect.objectContaining({ id: 't1' }),
+      );
+      expect(mockTrpcClient.message.getMessages.query).toHaveBeenCalledWith(
+        expect.objectContaining({ topicId: 't1' }),
+      );
+      expect(consoleSpy).toHaveBeenCalled();
+    });
+
+    it('should skip message query entirely when --no-messages flag is set', async () => {
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1', '--no-messages']);
+
+      // getTopicDetail is still called (for metadata)
+      expect(mockTrpcClient.topic.getTopicDetail.query).toHaveBeenCalled();
+      // but getMessages must NOT be called
+      expect(mockTrpcClient.message.getMessages.query).not.toHaveBeenCalled();
+    });
+
+    it('should output json when --json flag is set', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([
+        { content: 'Hello', id: 'm1', role: 'user' },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1', '--json']);
+
+      const calls = consoleSpy.mock.calls.flat().join('');
+      const parsed = JSON.parse(calls);
+      expect(parsed.topic.id).toBe('t1');
+      expect(parsed.messages).toHaveLength(1);
+      expect(parsed.messages[0]).toHaveProperty('role', 'user');
+      expect(parsed.messages[0]).toHaveProperty('content', 'Hello');
+    });
+
+    it('should output json with empty messages for --no-messages --json', async () => {
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1', '--no-messages', '--json']);
+
+      expect(mockTrpcClient.message.getMessages.query).not.toHaveBeenCalled();
+      const calls = consoleSpy.mock.calls.flat().join('');
+      const parsed = JSON.parse(calls);
+      expect(parsed.topic.id).toBe('t1');
+      expect(parsed.messages).toHaveLength(0);
+    });
+
+    it('should respect -L for message page size', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1', '-L', '10']);
+
+      expect(mockTrpcClient.message.getMessages.query).toHaveBeenCalledWith(
+        expect.objectContaining({ pageSize: 10, topicId: 't1' }),
+      );
+    });
+
+    it('should slice messages with --from and --to', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([
+        { content: 'msg1', id: 'm1', role: 'user' },
+        { content: 'msg2', id: 'm2', role: 'assistant' },
+        { content: 'msg3', id: 'm3', role: 'user' },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1', '--from', '2', '--to', '3']);
+
+      // Should print only m2 and m3 (index 1 and 2)
+      const output = consoleSpy.mock.calls.flat().join('\n');
+      expect(output).toContain('msg2');
+      expect(output).toContain('msg3');
+      expect(output).not.toContain('msg1');
+    });
+
+    it('should render tool calls inline', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([
+        {
+          content: "I'll search for that.",
+          id: 'm1',
+          role: 'assistant',
+          tools: [
+            {
+              function: { arguments: '{"query":"lobehub"}', name: 'web_search' },
+              id: 'call_1',
+              type: 'function',
+            },
+          ],
+        },
+        { content: 'search results...', id: 'm2', role: 'tool' },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1']);
+
+      const output = consoleSpy.mock.calls.flat().join('\n');
+      expect(output).toContain('web_search');
+      expect(output).toContain('lobehub');
+    });
+
+    it('should render threaded messages with indentation', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([
+        { content: 'Parent message', id: 'm1', parentId: null, role: 'user' },
+        { content: 'Thread reply', id: 'm2', parentId: 'm1', role: 'assistant' },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'view', 't1']);
+
+      const output = consoleSpy.mock.calls.flat().join('\n');
+      expect(output).toContain('Parent message');
+      expect(output).toContain('Thread reply');
+      // thread reply should appear after parent (basic ordering check)
+      expect(output.indexOf('Thread reply')).toBeGreaterThan(output.indexOf('Parent message'));
+    });
+  });
 });

apps/cli/src/commands/topic.ts

@@ -332,4 +332,170 @@ export function registerTopicCommand(program: Command) {
 
       printTable(rows, ['ID', 'TITLE', 'UPDATED']);
     });
+
+  // ── view ──────────────────────────────────────────────
+
+  topic
+    .command('view <id>')
+    .description('View topic details and its messages')
+    .option('-L, --limit <n>', 'Max messages to fetch per page', '50')
+    .option('--from <n>', 'Show messages starting from this index (1-based)', '1')
+    .option('--to <n>', 'Show messages up to this index (inclusive)')
+    .option('--no-messages', 'Skip messages, show topic metadata only')
+    .option('--json', 'Output JSON')
+    .action(
+      async (
+        id: string,
+        options: {
+          from?: string;
+          json?: boolean;
+          limit?: string;
+          messages?: boolean;
+          to?: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+
+        // ── 1. Fetch topic detail (single query by id) ──
+        const topicDetail = await client.topic.getTopicDetail.query({ id } as any);
+
+        // ── 2. Fetch messages only when needed ──
+        if (options.messages === false) {
+          // --no-messages: skip message query entirely
+          if (options.json) {
+            console.log(JSON.stringify({ messages: [], topic: topicDetail ?? { id } }, null, 2));
+            return;
+          }
+          console.log('');
+          console.log(
+            `${pc.bold('Topic:')}   ${pc.cyan((topicDetail as any)?.title ?? id)}  ${pc.dim(`(${id})`)}`,
+          );
+          console.log('');
+          return;
+        }
+
+        const msgLimit = Number.parseInt(options.limit || '50', 10);
+        const msgResult = await client.message.getMessages.query({
+          pageSize: msgLimit,
+          topicId: id,
+        } as any);
+        const allMessages: any[] = Array.isArray(msgResult)
+          ? msgResult
+          : ((msgResult as any).items ?? []);
+
+        // Apply --from / --to slicing (1-based)
+        const fromIdx = Math.max(1, Number.parseInt(options.from || '1', 10)) - 1;
+        const toIdx = options.to ? Number.parseInt(options.to, 10) : allMessages.length;
+        const messages = allMessages.slice(fromIdx, toIdx);
+
+        if (options.json) {
+          console.log(
+            JSON.stringify(
+              {
+                messages: messages.map((m: any) => ({
+                  content: m.content ?? null,
+                  createdAt: m.createdAt ?? null,
+                  id: m.id,
+                  parentId: m.parentId ?? null,
+                  role: m.role,
+                  threadId: m.threadId ?? null,
+                  tools: m.tools ?? null,
+                })),
+                topic: { id },
+              },
+              null,
+              2,
+            ),
+          );
+          return;
+        }
+
+        // ── Header ──
+        const t = topicDetail as any;
+        console.log('');
+        console.log(`${pc.bold('Topic:')}   ${pc.cyan(t?.title ?? id)}  ${pc.dim(`(${id})`)}`);
+        if (t?.favorite) console.log(`${pc.bold('Favorite:')} ★`);
+        if (t?.updatedAt) console.log(`${pc.bold('Updated:')}  ${timeAgo(t.updatedAt)}`);
+        if (t?.status) console.log(`${pc.bold('Status:')}   ${t.status}`);
+        if (t?.model) console.log(`${pc.bold('Model:')}    ${t.model}${t.provider ? ` (${t.provider})` : ''}`);
+        console.log('');
+
+        // ── Messages ──
+        if (messages.length === 0) {
+          console.log(pc.dim('  (no messages)'));
+          return;
+        }
+
+        // Build parentId → children map for thread display
+        const childrenOf = new Map<string | null, any[]>();
+        for (const m of messages) {
+          const key = m.parentId ?? null;
+          if (!childrenOf.has(key)) childrenOf.set(key, []);
+          childrenOf.get(key)!.push(m);
+        }
+
+        const printMessage = (m: any, depth: number) => {
+          const indent = '  '.repeat(depth + 1);
+          const roleLabel =
+            m.role === 'user'
+              ? pc.green('user     ')
+              : m.role === 'tool'
+                ? pc.yellow('tool     ')
+                : pc.blue('assistant');
+          const threadMark = depth > 0 ? pc.dim('↳ ') : '';
+
+          // Full content (no truncation)
+          const content = (m.content || '').trim();
+          if (content) {
+            console.log(`${indent}${threadMark}${roleLabel}  ${content}`);
+          }
+
+          // Tool calls (assistant requesting tools)
+          if (m.tools && Array.isArray(m.tools) && m.tools.length > 0) {
+            for (const tool of m.tools) {
+              const toolName = tool.function?.name ?? tool.id ?? 'unknown';
+              const toolArgs = tool.function?.arguments
+                ? (() => {
+                    try {
+                      return JSON.stringify(JSON.parse(tool.function.arguments), null, 2)
+                        .split('\n')
+                        .map((l: string) => `${indent}    ${l}`)
+                        .join('\n');
+                    } catch {
+                      return `${indent}    ${tool.function.arguments}`;
+                    }
+                  })()
+                : '';
+              console.log(`${indent}  ${pc.yellow('⚙')} ${pc.bold(toolName)}`);
+              if (toolArgs) console.log(toolArgs);
+            }
+          }
+
+          // Render thread children recursively
+          const children = childrenOf.get(m.id) ?? [];
+          for (const child of children) {
+            printMessage(child, depth + 1);
+          }
+        };
+
+        // Print only top-level messages (parentId === null/undefined, or parentId not in current page)
+        const msgIds = new Set(messages.map((m: any) => m.id));
+        const topLevel = messages.filter(
+          (m: any) => !m.parentId || !msgIds.has(m.parentId),
+        );
+
+        for (const m of topLevel) {
+          printMessage(m, 0);
+        }
+
+        if (allMessages.length > msgLimit) {
+          console.log('');
+          console.log(
+            pc.dim(
+              `  … total ${allMessages.length} messages, showing ${fromIdx + 1}–${Math.min(toIdx, allMessages.length)}. Use -L / --from / --to to paginate.`,
+            ),
+          );
+        }
+      },
+    );
 }

apps/cli/src/commands/verify.test.ts

@@ -0,0 +1,90 @@
+import { Command } from 'commander';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { registerVerifyCommand } from './verify';
+
+const { mockTrpcClient } = vi.hoisted(() => ({
+  mockTrpcClient: {
+    verify: {
+      createRubric: { mutate: vi.fn() },
+      getRubric: { query: vi.fn() },
+      updateRubric: { mutate: vi.fn() },
+    },
+  },
+}));
+
+const { getTrpcClient: mockGetTrpcClient } = vi.hoisted(() => ({
+  getTrpcClient: vi.fn(),
+}));
+
+vi.mock('../api/client', () => ({ getTrpcClient: mockGetTrpcClient }));
+vi.mock('../utils/logger', () => ({
+  log: { debug: vi.fn(), error: vi.fn(), info: vi.fn(), warn: vi.fn() },
+  setVerbose: vi.fn(),
+}));
+
+describe('verify rubric config commands', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
+    mockTrpcClient.verify.createRubric.mutate.mockReset().mockResolvedValue({ id: 'rub-1' });
+    mockTrpcClient.verify.updateRubric.mutate.mockReset().mockResolvedValue(undefined);
+    mockTrpcClient.verify.getRubric.query.mockReset();
+  });
+
+  afterEach(() => consoleSpy.mockRestore());
+
+  const run = async (args: string[]) => {
+    const program = new Command();
+    program.exitOverride();
+    registerVerifyCommand(program);
+    await program.parseAsync(['node', 'lh', 'verify', ...args]);
+  };
+
+  it('passes maxRepairRounds config when creating a rubric', async () => {
+    await run(['rubric', 'create', '-t', 'Standard', '--max-repair-rounds', '3']);
+
+    expect(mockTrpcClient.verify.createRubric.mutate).toHaveBeenCalledWith({
+      config: { maxRepairRounds: 3 },
+      description: undefined,
+      title: 'Standard',
+    });
+  });
+
+  it('omits config when no max-repair-rounds flag is given', async () => {
+    await run(['rubric', 'create', '-t', 'Standard']);
+
+    expect(mockTrpcClient.verify.createRubric.mutate).toHaveBeenCalledWith({
+      config: undefined,
+      description: undefined,
+      title: 'Standard',
+    });
+  });
+
+  it('updates only the config when max-repair-rounds is passed', async () => {
+    await run(['rubric', 'update', 'rub-1', '--max-repair-rounds', '0']);
+
+    expect(mockTrpcClient.verify.updateRubric.mutate).toHaveBeenCalledWith({
+      id: 'rub-1',
+      value: { config: { maxRepairRounds: 0 } },
+    });
+  });
+
+  it('views a rubric and prints its repair-round config', async () => {
+    mockTrpcClient.verify.getRubric.query.mockResolvedValue({
+      config: { maxRepairRounds: 4 },
+      description: 'desc',
+      id: 'rub-1',
+      title: 'Standard',
+    });
+
+    await run(['rubric', 'view', 'rub-1']);
+
+    expect(mockTrpcClient.verify.getRubric.query).toHaveBeenCalledWith({ id: 'rub-1' });
+    const printed = consoleSpy.mock.calls.map((c) => String(c[0])).join('\n');
+    expect(printed).toContain('Standard');
+    expect(printed).toContain('4');
+  });
+});

apps/cli/src/commands/verify.ts

@@ -0,0 +1,455 @@
+import type { Command } from 'commander';
+import pc from 'picocolors';
+
+import { getTrpcClient } from '../api/client';
+import { confirm, outputJson, printTable, timeAgo, truncate } from '../utils/format';
+import { log } from '../utils/logger';
+
+// ── Helpers ────────────────────────────────────────────────
+
+type VerifierType = 'agent' | 'llm' | 'program';
+type OnFail = 'auto_repair' | 'manual';
+type Decision = 'accepted' | 'overridden' | 'rejected';
+
+const VERIFIER_TYPES: VerifierType[] = ['program', 'agent', 'llm'];
+const ON_FAIL: OnFail[] = ['manual', 'auto_repair'];
+const DECISIONS: Decision[] = ['accepted', 'rejected', 'overridden'];
+
+function parseConfig(raw?: string): Record<string, unknown> | undefined {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    log.error('--config must be valid JSON');
+    process.exit(1);
+  }
+}
+
+function assertEnum<T extends string>(value: T | undefined, allowed: T[], flag: string): void {
+  if (value !== undefined && !allowed.includes(value)) {
+    log.error(`${flag} must be one of: ${allowed.join(', ')}`);
+    process.exit(1);
+  }
+}
+
+// ── Command Registration ───────────────────────────────────
+
+export function registerVerifyCommand(program: Command) {
+  const verify = program
+    .command('verify')
+    .description('Manage the Agent Run delivery checker (criteria, rubrics, plans, results)');
+
+  // ════════════ criteria ════════════
+  const criterion = verify.command('criterion').description('Reusable pass/fail standards');
+
+  criterion
+    .command('list')
+    .description('List criteria')
+    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
+    .action(async (options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const items = await client.verify.listCriteria.query();
+
+      if (options.json !== undefined) {
+        outputJson(items, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (items.length === 0) return void console.log('No criteria found.');
+      printTable(
+        items.map((c) => [
+          c.id,
+          truncate(c.title, 60),
+          c.verifierType,
+          c.required ? 'gate' : 'soft',
+          c.onFail,
+          c.updatedAt ? timeAgo(c.updatedAt) : '',
+        ]),
+        ['ID', 'TITLE', 'TYPE', 'BLOCK', 'ON-FAIL', 'UPDATED'],
+      );
+    });
+
+  criterion
+    .command('create')
+    .description('Create a criterion')
+    .requiredOption('-t, --title <title>', 'Criterion title')
+    .requiredOption('--type <type>', `Verifier type (${VERIFIER_TYPES.join('|')})`)
+    .option('--on-fail <strategy>', `Action on failure (${ON_FAIL.join('|')})`)
+    .option('--soft', 'Non-blocking (required=false); defaults to blocking')
+    .option('--config <json>', 'Verifier config as JSON')
+    .option('--doc <id>', 'Linked guidance document id')
+    .action(
+      async (options: {
+        config?: string;
+        doc?: string;
+        onFail?: OnFail;
+        soft?: boolean;
+        title: string;
+        type: VerifierType;
+      }) => {
+        assertEnum(options.type, VERIFIER_TYPES, '--type');
+        assertEnum(options.onFail, ON_FAIL, '--on-fail');
+        const client = await getTrpcClient();
+        const result = await client.verify.createCriterion.mutate({
+          documentId: options.doc,
+          onFail: options.onFail,
+          required: options.soft ? false : undefined,
+          title: options.title,
+          verifierConfig: parseConfig(options.config),
+          verifierType: options.type,
+        });
+        console.log(`${pc.green('✓')} Created criterion ${pc.bold((result as any).id)}`);
+      },
+    );
+
+  criterion
+    .command('delete <id>')
+    .description('Delete a criterion')
+    .option('--yes', 'Skip confirmation')
+    .action(async (id: string, options: { yes?: boolean }) => {
+      if (!options.yes && !(await confirm(`Delete criterion ${id}?`)))
+        return void console.log('Cancelled.');
+      const client = await getTrpcClient();
+      await client.verify.deleteCriterion.mutate({ id });
+      console.log(`${pc.green('✓')} Deleted criterion ${pc.bold(id)}`);
+    });
+
+  // ════════════ rubrics ════════════
+  const rubric = verify.command('rubric').description('Named groups of criteria');
+
+  rubric
+    .command('list')
+    .description('List rubrics')
+    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
+    .action(async (options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const items = await client.verify.listRubrics.query();
+      if (options.json !== undefined) {
+        outputJson(items, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (items.length === 0) return void console.log('No rubrics found.');
+      printTable(
+        items.map((r) => [
+          r.id,
+          truncate(r.title, 60),
+          truncate(r.description || '', 60),
+          r.updatedAt ? timeAgo(r.updatedAt) : '',
+        ]),
+        ['ID', 'TITLE', 'DESCRIPTION', 'UPDATED'],
+      );
+    });
+
+  rubric
+    .command('create')
+    .description('Create a rubric')
+    .requiredOption('-t, --title <title>', 'Rubric title')
+    .option('-d, --description <text>', 'Rubric description')
+    .option('--max-repair-rounds <n>', 'Cap on automatic repair rounds (0-5)')
+    .action(async (options: { description?: string; maxRepairRounds?: string; title: string }) => {
+      const client = await getTrpcClient();
+      const result = await client.verify.createRubric.mutate({
+        config:
+          options.maxRepairRounds !== undefined
+            ? { maxRepairRounds: Number(options.maxRepairRounds) }
+            : undefined,
+        description: options.description,
+        title: options.title,
+      });
+      console.log(`${pc.green('✓')} Created rubric ${pc.bold((result as any).id)}`);
+    });
+
+  rubric
+    .command('view <id>')
+    .description('Show a rubric and its run-policy config')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (id: string, options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const item = await client.verify.getRubric.query({ id });
+      if (!item) return void log.error('Rubric not found.');
+      if (options.json !== undefined) {
+        outputJson(item, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      console.log(`${pc.bold('ID')}            ${item.id}`);
+      console.log(`${pc.bold('Title')}         ${item.title}`);
+      if (item.description) console.log(`${pc.bold('Description')}   ${item.description}`);
+      const maxRepairRounds = (item.config as { maxRepairRounds?: number } | null)?.maxRepairRounds;
+      console.log(`${pc.bold('Repair rounds')} ${maxRepairRounds ?? pc.dim('default')}`);
+    });
+
+  rubric
+    .command('update <id>')
+    .description('Update a rubric (title / description / run-policy config)')
+    .option('-t, --title <title>', 'New title')
+    .option('-d, --description <text>', 'New description')
+    .option('--max-repair-rounds <n>', 'Cap on automatic repair rounds (0-5)')
+    .action(
+      async (
+        id: string,
+        options: { description?: string; maxRepairRounds?: string; title?: string },
+      ) => {
+        const client = await getTrpcClient();
+        const value: {
+          config?: { maxRepairRounds?: number };
+          description?: string;
+          title?: string;
+        } = {};
+        if (options.title !== undefined) value.title = options.title;
+        if (options.description !== undefined) value.description = options.description;
+        if (options.maxRepairRounds !== undefined)
+          value.config = { maxRepairRounds: Number(options.maxRepairRounds) };
+        await client.verify.updateRubric.mutate({ id, value });
+        console.log(`${pc.green('✓')} Updated rubric ${pc.bold(id)}`);
+      },
+    );
+
+  rubric
+    .command('delete <id>')
+    .description('Delete a rubric')
+    .option('--yes', 'Skip confirmation')
+    .action(async (id: string, options: { yes?: boolean }) => {
+      if (!options.yes && !(await confirm(`Delete rubric ${id}?`)))
+        return void console.log('Cancelled.');
+      const client = await getTrpcClient();
+      await client.verify.deleteRubric.mutate({ id });
+      console.log(`${pc.green('✓')} Deleted rubric ${pc.bold(id)}`);
+    });
+
+  rubric
+    .command('criteria <rubricId>')
+    .description('List criteria in a rubric')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (rubricId: string, options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const items = await client.verify.getRubricCriteria.query({ rubricId });
+      if (options.json !== undefined) {
+        outputJson(items, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (items.length === 0) return void console.log('No criteria in this rubric.');
+      printTable(
+        items.map((c: any) => [
+          c.id,
+          truncate(c.title, 60),
+          c.verifierType,
+          c.required ? 'gate' : 'soft',
+        ]),
+        ['ID', 'TITLE', 'TYPE', 'BLOCK'],
+      );
+    });
+
+  rubric
+    .command('set-criteria <rubricId> <criterionIds...>')
+    .description('Set the criteria a rubric aggregates (order preserved)')
+    .action(async (rubricId: string, criterionIds: string[]) => {
+      const client = await getTrpcClient();
+      await client.verify.setRubricCriteria.mutate({
+        criteria: criterionIds.map((criterionId, i) => ({ criterionId, sortOrder: i })),
+        rubricId,
+      });
+      console.log(
+        `${pc.green('✓')} Rubric ${pc.bold(rubricId)} now has ${criterionIds.length} criterion(s)`,
+      );
+    });
+
+  // ════════════ per-run plan ════════════
+  const plan = verify.command('plan').description('Per-run check plan lifecycle');
+
+  plan
+    .command('generate <operationId>')
+    .description('Generate a draft check plan for a run')
+    .requiredOption('--goal <goal>', "The run's task/instruction the plan must satisfy")
+    .option('--rubric <id>', 'Mounted rubric id')
+    .option('--criteria <ids>', 'Ad-hoc criterion ids (comma-separated)')
+    .option('--ai', 'Let the LLM propose additional criteria')
+    .option('--max-ai <n>', 'Max AI-proposed criteria')
+    .option('--model <model>', 'Model (required with --ai)')
+    .option('--provider <provider>', 'Provider (required with --ai)')
+    .option('--context <text>', 'Extra context for the AI prompt')
+    .option('--json [fields]', 'Output JSON')
+    .action(
+      async (
+        operationId: string,
+        options: {
+          ai?: boolean;
+          context?: string;
+          criteria?: string;
+          goal: string;
+          json?: boolean | string;
+          maxAi?: string;
+          model?: string;
+          provider?: string;
+          rubric?: string;
+        },
+      ) => {
+        if (options.ai && (!options.model || !options.provider)) {
+          log.error('--ai requires --model and --provider');
+          process.exit(1);
+        }
+        const client = await getTrpcClient();
+        const items = await client.verify.generateDraftPlan.mutate({
+          context: options.context,
+          enableAiGeneration: options.ai,
+          goal: options.goal,
+          maxAiCriteria: options.maxAi ? Number.parseInt(options.maxAi, 10) : undefined,
+          modelConfig:
+            options.model && options.provider
+              ? { model: options.model, provider: options.provider }
+              : undefined,
+          operationId,
+          verifyCriteriaIds: options.criteria
+            ?.split(',')
+            .map((s) => s.trim())
+            .filter(Boolean),
+          verifyRubricId: options.rubric ?? null,
+        });
+        if (options.json !== undefined) {
+          outputJson(items, typeof options.json === 'string' ? options.json : undefined);
+          return;
+        }
+        console.log(`${pc.green('✓')} Draft plan: ${pc.bold(String(items.length))} item(s)`);
+        printTable(
+          items.map((i: any) => [
+            String(i.index),
+            truncate(i.title, 60),
+            i.verifierType,
+            i.required ? 'gate' : 'soft',
+          ]),
+          ['#', 'TITLE', 'TYPE', 'BLOCK'],
+        );
+      },
+    );
+
+  plan
+    .command('state <operationId>')
+    .description('Show the verify state (status + frozen plan) of a run')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (operationId: string, options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const state = await client.verify.getVerifyState.query({ operationId });
+      if (options.json !== undefined) {
+        outputJson(state, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (!state) return void console.log('No verify state for this run.');
+      console.log(`${pc.bold('status')}: ${state.verifyStatus ?? pc.dim('(none)')}`);
+      console.log(
+        `${pc.bold('confirmed')}: ${state.verifyPlanConfirmedAt ? timeAgo(state.verifyPlanConfirmedAt) : pc.dim('no')}`,
+      );
+      const items = (state.verifyPlan ?? []) as any[];
+      console.log(`${pc.bold('plan')}: ${items.length} item(s)`);
+      if (items.length > 0)
+        printTable(
+          items.map((i) => [
+            String(i.index),
+            truncate(i.title, 60),
+            i.verifierType,
+            i.required ? 'gate' : 'soft',
+          ]),
+          ['#', 'TITLE', 'TYPE', 'BLOCK'],
+        );
+    });
+
+  plan
+    .command('confirm <operationId>')
+    .description('Freeze (confirm) the draft plan')
+    .action(async (operationId: string) => {
+      const client = await getTrpcClient();
+      await client.verify.confirmPlan.mutate({ operationId });
+      console.log(`${pc.green('✓')} Confirmed plan for run ${pc.bold(operationId)}`);
+    });
+
+  plan
+    .command('skip <operationId>')
+    .description('Skip verification for a run')
+    .action(async (operationId: string) => {
+      const client = await getTrpcClient();
+      await client.verify.skipPlan.mutate({ operationId });
+      console.log(`${pc.green('✓')} Skipped verification for run ${pc.bold(operationId)}`);
+    });
+
+  // ════════════ run / results ════════════
+  verify
+    .command('run <operationId>')
+    .description('Execute the confirmed plan against a deliverable (LLM judge)')
+    .requiredOption('--goal <goal>', "The run's task")
+    .requiredOption('--deliverable <text>', 'The output to judge')
+    .requiredOption('--model <model>', 'Judge model')
+    .requiredOption('--provider <provider>', 'Judge provider')
+    .option('--no-batch', 'Judge each item separately instead of one batched call')
+    .option('--json [fields]', 'Output JSON')
+    .action(
+      async (
+        operationId: string,
+        options: {
+          batch?: boolean;
+          deliverable: string;
+          goal: string;
+          json?: boolean | string;
+          model: string;
+          provider: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const results = await client.verify.executeVerify.mutate({
+          batchLlm: options.batch,
+          deliverable: options.deliverable,
+          goal: options.goal,
+          modelConfig: { model: options.model, provider: options.provider },
+          operationId,
+        });
+        if (options.json !== undefined) {
+          outputJson(results, typeof options.json === 'string' ? options.json : undefined);
+          return;
+        }
+        printResults(results);
+      },
+    );
+
+  verify
+    .command('results <operationId>')
+    .description('List check results for a run')
+    .option('--json [fields]', 'Output JSON')
+    .action(async (operationId: string, options: { json?: boolean | string }) => {
+      const client = await getTrpcClient();
+      const results = await client.verify.listResults.query({ operationId });
+      if (options.json !== undefined) {
+        outputJson(results, typeof options.json === 'string' ? options.json : undefined);
+        return;
+      }
+      if (results.length === 0) return void console.log('No results yet.');
+      printResults(results);
+    });
+
+  // ════════════ feedback ════════════
+  verify
+    .command('decision <resultId> <decision>')
+    .description(`Record human feedback on a result (${DECISIONS.join('|')})`)
+    .action(async (resultId: string, decision: Decision) => {
+      assertEnum(decision, DECISIONS, 'decision');
+      const client = await getTrpcClient();
+      await client.verify.submitDecision.mutate({ decision, resultId });
+      console.log(`${pc.green('✓')} Recorded ${pc.bold(decision)} on result ${pc.bold(resultId)}`);
+    });
+}
+
+function printResults(results: any[]): void {
+  printTable(
+    results.map((r) => [
+      truncate(r.checkItemTitle || r.checkItemId, 50),
+      statusColor(r.status),
+      r.verdict ?? '',
+      r.confidence != null ? String(r.confidence) : '',
+      r.required ? 'gate' : 'soft',
+      truncate(r.suggestion || '', 40),
+    ]),
+    ['CHECK', 'STATUS', 'VERDICT', 'CONF', 'BLOCK', 'SUGGESTION'],
+  );
+}
+
+function statusColor(status: string): string {
+  if (status === 'passed') return pc.green(status);
+  if (status === 'failed') return pc.red(status);
+  if (status === 'running') return pc.yellow(status);
+  return pc.dim(status);
+}

apps/cli/src/device/register.ts

@@ -0,0 +1,40 @@
+import os from 'node:os';
+
+import type { DeviceIdentity } from '@lobechat/device-identity';
+import { deriveDeviceId } from '@lobechat/device-identity';
+
+import { createLambdaClient } from '../api/client';
+
+/**
+ * Resolve a stable device identity. An explicit `--device-id` wins (lets a user
+ * pin a VM to a fixed identity); otherwise derive from the machine id so the
+ * same machine + user maps to one device across reconnects. Returns undefined
+ * when neither an explicit id nor a userId is available.
+ */
+export function resolveDeviceIdentity(
+  userId: string | undefined,
+  explicitDeviceId?: string,
+): DeviceIdentity | undefined {
+  if (explicitDeviceId) return { deviceId: explicitDeviceId, identitySource: 'fallback' };
+  if (userId) return deriveDeviceId(userId);
+  return undefined;
+}
+
+/**
+ * Register this device in the server registry. Shared by `lh login` (so the
+ * device row exists right after auth) and `lh connect` (so the row exists
+ * before the WS opens). Best-effort by contract: callers should wrap this in a
+ * try/catch and treat any failure as non-fatal.
+ */
+export async function registerDevice(
+  auth: { serverUrl: string; token: string; tokenType: 'apiKey' | 'jwt' | 'serviceToken' },
+  identity: DeviceIdentity,
+): Promise<void> {
+  const trpc = createLambdaClient(auth);
+  await trpc.device.register.mutate({
+    deviceId: identity.deviceId,
+    hostname: os.hostname(),
+    identitySource: identity.identitySource,
+    platform: process.platform,
+  });
+}

apps/cli/src/program.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander';
 
 import { registerAgentCommand } from './commands/agent';
 import { registerAgentGroupCommand } from './commands/agent-group';
+import { registerAgentSignalCommand } from './commands/agent-signal';
 import { registerBotCommand } from './commands/bot';
 import { registerCompletionCommand } from './commands/completion';
 import { registerConfigCommand } from './commands/config';
@@ -33,6 +34,7 @@ import { registerTaskCommand } from './commands/task';
 import { registerThreadCommand } from './commands/thread';
 import { registerTopicCommand } from './commands/topic';
 import { registerUserCommand } from './commands/user';
+import { registerVerifyCommand } from './commands/verify';
 
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
@@ -58,6 +60,7 @@ export function createProgram() {
   registerMemoryCommand(program);
   registerAgentCommand(program);
   registerAgentGroupCommand(program);
+  registerAgentSignalCommand(program);
   registerBotCommand(program);
   registerGenerateCommand(program);
   registerFileCommand(program);
@@ -73,6 +76,7 @@ export function createProgram() {
   registerProviderCommand(program);
   registerPluginCommand(program);
   registerUserCommand(program);
+  registerVerifyCommand(program);
   registerConfigCommand(program);
   registerEvalCommand(program);
   registerMigrateCommand(program);

apps/cli/src/settings/index.test.ts

@@ -5,7 +5,13 @@ import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { log } from '../utils/logger';
-import { loadSettings, normalizeUrl, resolveServerUrl, saveSettings } from './index';
+import {
+  loadOrCreateConnectionId,
+  loadSettings,
+  normalizeUrl,
+  resolveServerUrl,
+  saveSettings,
+} from './index';
 
 const tmpDir = path.join(os.tmpdir(), 'lobehub-cli-test-settings');
 const settingsDir = path.join(tmpDir, '.lobehub');
@@ -91,4 +97,22 @@ describe('settings', () => {
 
     expect(resolveServerUrl()).toBe('https://app.lobehub.com');
   });
+
+  it('should create a connectionId once and reuse it across calls', () => {
+    const first = loadOrCreateConnectionId();
+    expect(first).toMatch(/[\da-f-]{36}/);
+
+    // Persisted in its own file, independent of settings.json.
+    expect(fs.existsSync(path.join(settingsDir, 'connection-id'))).toBe(true);
+    expect(loadOrCreateConnectionId()).toBe(first);
+  });
+
+  it('should keep the connectionId even when settings.json is cleared', () => {
+    const id = loadOrCreateConnectionId();
+    // Clearing official-server settings unlinks settings.json — connectionId must survive.
+    saveSettings({ serverUrl: 'https://app.lobehub.com/' });
+
+    expect(fs.existsSync(settingsFile)).toBe(false);
+    expect(loadOrCreateConnectionId()).toBe(id);
+  });
 });

apps/cli/src/settings/index.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -14,6 +15,9 @@ export interface StoredSettings {
 const LOBEHUB_DIR_NAME = process.env.LOBEHUB_CLI_HOME || '.lobehub';
 const SETTINGS_DIR = path.join(os.homedir(), LOBEHUB_DIR_NAME);
 const SETTINGS_FILE = path.join(SETTINGS_DIR, 'settings.json');
+// Kept in its own file rather than settings.json, which is unlinked whenever
+// all server/gateway URLs are default — the connectionId must persist regardless.
+const CONNECTION_ID_FILE = path.join(SETTINGS_DIR, 'connection-id');
 
 export function normalizeUrl(url: string | undefined): string | undefined {
   return url ? url.replace(/\/$/, '') : undefined;
@@ -54,6 +58,31 @@ export function saveSettings(settings: StoredSettings): void {
   fs.writeFileSync(SETTINGS_FILE, JSON.stringify(normalized, null, 2), { mode: 0o600 });
 }
 
+/**
+ * Stable per-install connection routing key for `lh connect`. Decoupled from
+ * the (machine-derived, shared-across-clients) deviceId so the gateway only
+ * replaces this install's own stale socket — a co-running desktop app on the
+ * same machine keeps its connection. Persisted under the CLI home dir, so a
+ * separate `LOBEHUB_CLI_HOME` (e.g. a dev build) naturally gets its own id.
+ */
+export function loadOrCreateConnectionId(): string {
+  try {
+    const existing = fs.readFileSync(CONNECTION_ID_FILE, 'utf8').trim();
+    if (existing) return existing;
+  } catch {
+    // not yet created
+  }
+
+  const id = randomUUID();
+  try {
+    fs.mkdirSync(SETTINGS_DIR, { mode: 0o700, recursive: true });
+    fs.writeFileSync(CONNECTION_ID_FILE, id, { mode: 0o600 });
+  } catch {
+    // best-effort: an unwritable home dir just means a fresh id per run
+  }
+  return id;
+}
+
 export function loadSettings(): StoredSettings | null {
   if (!fs.existsSync(SETTINGS_FILE)) return null;
 

apps/cli/src/tools/index.test.ts

@@ -3,6 +3,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
+import { ShellProcessManager } from '@lobechat/local-file-shell';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { executeToolCall } from './index';
@@ -27,15 +28,17 @@ describe('executeToolCall', () => {
     fs.rmSync(tmpDir, { force: true, recursive: true });
   });
 
-  it('should dispatch readFile', async () => {
+  it('should dispatch readFile with formatted content and structured state', async () => {
     const filePath = path.join(tmpDir, 'test.txt');
     await writeFile(filePath, 'hello world');
 
     const result = await executeToolCall('readFile', JSON.stringify({ path: filePath }));
 
     expect(result.success).toBe(true);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.content).toContain('hello world');
+    // content is now the formatted prompt text, not raw JSON
+    expect(result.content).toContain('hello world');
+    // structured payload travels in `state` for client renders
+    expect((result.state as { content: string }).content).toContain('hello world');
   });
 
   it('should dispatch writeFile', async () => {
@@ -47,6 +50,7 @@ describe('executeToolCall', () => {
     );
 
     expect(result.success).toBe(true);
+    expect((result.state as { path: string }).path).toBe(filePath);
     expect(fs.readFileSync(filePath, 'utf8')).toBe('written');
   });
 
@@ -57,8 +61,7 @@ describe('executeToolCall', () => {
     const result = await executeToolCall('readLocalFile', JSON.stringify({ path: filePath }));
 
     expect(result.success).toBe(true);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.content).toContain('legacy hello');
+    expect((result.state as { content: string }).content).toContain('legacy hello');
   });
 
   it('should dispatch runCommand', async () => {
@@ -68,8 +71,9 @@ describe('executeToolCall', () => {
     );
 
     expect(result.success).toBe(true);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.stdout).toContain('dispatched');
+    expect(result.content).toContain('dispatched');
+    const state = result.state as { output?: string; stdout?: string };
+    expect(state.stdout ?? state.output).toContain('dispatched');
   });
 
   it('should dispatch listFiles', async () => {
@@ -78,8 +82,7 @@ describe('executeToolCall', () => {
     const result = await executeToolCall('listFiles', JSON.stringify({ path: tmpDir }));
 
     expect(result.success).toBe(true);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.totalCount).toBeGreaterThan(0);
+    expect((result.state as { totalCount: number }).totalCount).toBeGreaterThan(0);
   });
 
   it('should dispatch globFiles', async () => {
@@ -91,8 +94,7 @@ describe('executeToolCall', () => {
     );
 
     expect(result.success).toBe(true);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.files).toContain('test.ts');
+    expect((result.state as { files: string[] }).files).toContain('test.ts');
   });
 
   it('should dispatch editFile', async () => {
@@ -109,6 +111,7 @@ describe('executeToolCall', () => {
     );
 
     expect(result.success).toBe(true);
+    expect((result.state as { replacements: number }).replacements).toBeGreaterThan(0);
     expect(fs.readFileSync(filePath, 'utf8')).toBe('new content');
   });
 
@@ -119,19 +122,15 @@ describe('executeToolCall', () => {
     expect(result.error).toContain('Unknown tool API');
   });
 
-  it('should handle tool that returns a string result', async () => {
-    // runCommand returns an object, but we test the string branch by mocking
-    // Actually, none of the tools return plain strings, so the JSON.stringify branch
-    // is always taken. The string check is for future-proofing.
-    // Let's verify the JSON output path
+  it('should carry structured state on file reads', async () => {
     const filePath = path.join(tmpDir, 'str.txt');
     await writeFile(filePath, 'content');
 
     const result = await executeToolCall('readFile', JSON.stringify({ path: filePath }));
 
     expect(result.success).toBe(true);
-    // Result should be valid JSON
-    expect(() => JSON.parse(result.content)).not.toThrow();
+    expect(result.state).toBeDefined();
+    expect(typeof result.content).toBe('string');
   });
 
   it('should return error for invalid JSON arguments', async () => {
@@ -150,6 +149,7 @@ describe('executeToolCall', () => {
     );
 
     expect(result.success).toBe(true);
+    expect(result.state).toBeDefined();
   });
 
   it('should dispatch searchFiles', async () => {
@@ -161,6 +161,7 @@ describe('executeToolCall', () => {
     );
 
     expect(result.success).toBe(true);
+    expect(result.state).toBeDefined();
   });
 
   it('should dispatch getCommandOutput', async () => {
@@ -169,9 +170,21 @@ describe('executeToolCall', () => {
       JSON.stringify({ shell_id: 'nonexistent' }),
     );
 
+    // The runtime envelopes a failed lookup as success:true with the failure in state
     expect(result.success).toBe(true);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.success).toBe(false);
+    expect((result.state as { success: boolean }).success).toBe(false);
+  });
+
+  it('should forward the gateway timeout to getCommandOutput polling', async () => {
+    const spy = vi
+      .spyOn(ShellProcessManager.prototype, 'getOutput')
+      .mockResolvedValue({ exit_code: 0, output: '', stderr: '', stdout: '', success: true });
+
+    // 3rd arg is the gateway per-call timeout; executeToolCall injects it into args
+    await executeToolCall('getCommandOutput', JSON.stringify({ shell_id: 'sid' }), 5000);
+
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ shell_id: 'sid', timeout: 5000 }));
+    spy.mockRestore();
   });
 
   it('should dispatch killCommand', async () => {
@@ -181,7 +194,6 @@ describe('executeToolCall', () => {
     );
 
     expect(result.success).toBe(true);
-    const parsed = JSON.parse(result.content);
-    expect(parsed.success).toBe(false);
+    expect((result.state as { success: boolean }).success).toBe(false);
   });
 });

apps/cli/src/tools/index.ts

@@ -1,41 +1,19 @@
 import { log } from '../utils/logger';
 import { checkPlatformCapability } from './checkPlatformCapability';
-import {
-  editLocalFile,
-  globLocalFiles,
-  grepContent,
-  listLocalFiles,
-  readLocalFile,
-  searchLocalFiles,
-  writeLocalFile,
-} from './file';
 import { getAgentProfile } from './getAgentProfile';
 import { cancelHeteroTask, runHeteroTask } from './heteroTask';
-import { getCommandOutput, killCommand, runCommand } from './shell';
+import { runLocalSystemTool } from './localSystemRuntime';
 
+/**
+ * CLI-only tools (platform agents). File/shell tools are handled separately by
+ * {@link runLocalSystemTool}, which routes them through
+ * `LocalSystemExecutionRuntime` so the result carries structured `state`.
+ */
 const methodMap: Record<string, (args: any) => Promise<unknown>> = {
   cancelHeteroTask,
   checkPlatformCapability,
   getAgentProfile,
-  editFile: editLocalFile,
-  getCommandOutput,
-  globFiles: globLocalFiles,
-  grepContent,
-  killCommand,
-  listFiles: listLocalFiles,
-  readFile: readLocalFile,
-  runCommand,
   runHeteroTask,
-  searchFiles: searchLocalFiles,
-  writeFile: writeLocalFile,
-
-  // Legacy aliases — older Gateway versions may still send the long form
-  editLocalFile,
-  globLocalFiles,
-  listLocalFiles,
-  readLocalFile,
-  searchLocalFiles,
-  writeLocalFile,
 };
 
 export async function executeToolCall(
@@ -45,19 +23,44 @@ export async function executeToolCall(
 ): Promise<{
   content: string;
   error?: string;
+  state?: unknown;
   success: boolean;
 }> {
-  const handler = methodMap[apiName];
-  if (!handler) {
-    return { content: '', error: `Unknown tool API: ${apiName}`, success: false };
+  let args: Record<string, any>;
+  try {
+    args = JSON.parse(argsStr);
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    log.error(`Tool call failed: ${apiName} - ${errorMsg}`);
+    return { content: '', error: errorMsg, success: false };
   }
 
+  const finalArgs =
+    typeof timeout === 'number' && Number.isFinite(timeout) && !('timeout' in args)
+      ? { ...args, timeout }
+      : args;
+
   try {
-    const args = JSON.parse(argsStr);
-    const finalArgs =
-      typeof timeout === 'number' && Number.isFinite(timeout) && !('timeout' in args)
-        ? { ...args, timeout }
-        : args;
+    // File/shell tools route through LocalSystemExecutionRuntime so `content` is
+    // the formatted prompt text and `state` carries the structured payload for
+    // client renders — matching the desktop gateway path (PR #15114).
+    const localResult = await runLocalSystemTool(apiName, finalArgs);
+    if (localResult) {
+      const { error } = localResult;
+      return {
+        content: localResult.content,
+        error:
+          error instanceof Error ? error.message : typeof error === 'string' ? error : undefined,
+        state: localResult.state,
+        success: localResult.success,
+      };
+    }
+
+    // CLI-only tools return raw domain payloads, serialized into `content`.
+    const handler = methodMap[apiName];
+    if (!handler) {
+      return { content: '', error: `Unknown tool API: ${apiName}`, success: false };
+    }
 
     const result = await handler(finalArgs);
     const content = typeof result === 'string' ? result : JSON.stringify(result);

apps/cli/src/tools/localSystemRuntime.ts

@@ -0,0 +1,197 @@
+import path from 'node:path';
+
+import type {
+  EditFileParams,
+  GetCommandOutputParams,
+  GlobFilesParams,
+  GrepContentParams,
+  KillCommandParams,
+  ListFilesParams,
+  ReadFileParams,
+  RunCommandParams,
+  SearchFilesParams,
+  WriteFileParams,
+} from '@lobechat/local-file-shell';
+import { type ILocalSystemService, LocalSystemExecutionRuntime } from '@lobechat/tool-runtime';
+
+import {
+  editLocalFile,
+  globLocalFiles,
+  grepContent,
+  listLocalFiles,
+  readLocalFile,
+  searchLocalFiles,
+  writeLocalFile,
+} from './file';
+import { getCommandOutput, killCommand, runCommand } from './shell';
+
+/**
+ * Output envelope produced by {@link runLocalSystemTool}. Mirrors
+ * `@lobechat/types`' `BuiltinServerRuntimeOutput`: `content` is the formatted
+ * prompt text fed to the LLM, while `state` carries the structured payload that
+ * client renders consume as `pluginState`.
+ */
+export interface LocalSystemToolOutput {
+  content: string;
+  error?: unknown;
+  state?: unknown;
+  success: boolean;
+}
+
+/**
+ * Stub for `ILocalSystemService` methods the CLI does not expose (batch read,
+ * move, rename). These are never routed by {@link runLocalSystemTool}; the
+ * interface just requires them, so we fail loudly if one is ever reached.
+ */
+const unsupported = (method: string) => (): Promise<never> =>
+  Promise.reject(new Error(`${method} is not supported by the LobeHub CLI`));
+
+/**
+ * Adapter wiring the CLI's `@lobechat/local-file-shell` functions (file ops) and
+ * shell wrappers (with the shared `ShellProcessManager`) into the shape the
+ * runtime expects. The runtime denormalizes its camelCase params back to the
+ * snake_case IPC shapes these functions consume — see `LocalSystemExecutionRuntime`.
+ */
+const localSystemService: ILocalSystemService = {
+  editLocalFile,
+  getCommandOutput,
+  globFiles: globLocalFiles,
+  grepContent,
+  killCommand,
+  listLocalFiles,
+  moveLocalFiles: unsupported('moveLocalFiles'),
+  readLocalFile,
+  readLocalFiles: unsupported('readLocalFiles'),
+  renameLocalFile: unsupported('renameLocalFile'),
+  runCommand,
+  searchLocalFiles,
+  writeFile: writeLocalFile,
+};
+
+const runtime = new LocalSystemExecutionRuntime(localSystemService);
+
+/**
+ * Legacy API name aliases used by older gateway versions. Normalized to the
+ * current tool names before dispatch.
+ */
+const LEGACY_API_ALIASES: Record<string, string> = {
+  editLocalFile: 'editFile',
+  globLocalFiles: 'globFiles',
+  listLocalFiles: 'listFiles',
+  readLocalFile: 'readFile',
+  searchLocalFiles: 'searchFiles',
+  writeLocalFile: 'writeFile',
+};
+
+/**
+ * Resolve a relative path against a scope (CWD). Mirrors the desktop gateway's
+ * inline copy of the renderer-side `resolveArgsWithScope` helper so the CLI and
+ * desktop produce identical scoping for search/grep tools.
+ */
+const resolveArgsWithScope = <T extends { scope?: string }>(args: T, pathField: string): T => {
+  const scope = args.scope;
+  const bag = args as Record<PropertyKey, unknown>;
+  const currentPath = typeof bag[pathField] === 'string' ? (bag[pathField] as string) : undefined;
+  if (!scope) return args;
+  if (!currentPath) return { ...args, [pathField]: scope };
+  if (path.isAbsolute(currentPath)) return args;
+  return { ...args, [pathField]: path.join(scope, currentPath) };
+};
+
+/**
+ * Route file/shell tool calls through `LocalSystemExecutionRuntime` so the
+ * result carries structured `state` (for client renders) and `content` is the
+ * formatted prompt text — matching the desktop gateway path (PR #15114).
+ *
+ * Returns `null` when `apiName` is not a local-system tool, so the caller can
+ * fall back to CLI-only tools (platform agents).
+ */
+export async function runLocalSystemTool(
+  apiName: string,
+  args: Record<string, any>,
+): Promise<LocalSystemToolOutput | null> {
+  const normalized = LEGACY_API_ALIASES[apiName] ?? apiName;
+
+  switch (normalized) {
+    case 'listFiles': {
+      const p = args as ListFilesParams;
+      return runtime.listFiles({
+        directoryPath: p.path,
+        limit: p.limit,
+        sortBy: p.sortBy,
+        sortOrder: p.sortOrder,
+      } as never);
+    }
+
+    case 'readFile': {
+      const p = args as ReadFileParams;
+      return runtime.readFile({
+        endLine: p.loc?.[1],
+        path: p.path,
+        startLine: p.loc?.[0],
+      });
+    }
+
+    case 'writeFile': {
+      return runtime.writeFile(args as WriteFileParams);
+    }
+
+    case 'editFile': {
+      const p = args as EditFileParams;
+      return runtime.editFile({
+        all: p.replace_all,
+        path: p.file_path,
+        replace: p.new_string,
+        search: p.old_string,
+      });
+    }
+
+    case 'searchFiles': {
+      const resolved = resolveArgsWithScope(
+        args as SearchFilesParams & { scope?: string },
+        'directory',
+      );
+      return runtime.searchFiles({ ...resolved, directory: resolved.directory || '' } as never);
+    }
+
+    case 'grepContent': {
+      const resolved = resolveArgsWithScope(args as GrepContentParams, 'path');
+      return runtime.grepContent(resolved as never);
+    }
+
+    case 'globFiles': {
+      const p = args as GlobFilesParams;
+      // Honor both `scope` (current manifest) and the `cwd` legacy alias.
+      return runtime.globFiles({ directory: p.scope ?? p.cwd, pattern: p.pattern });
+    }
+
+    case 'runCommand': {
+      // ComputerRuntime's RunCommandState reads `args.background`; the manifest
+      // exposes `run_in_background`. Without this normalize the state would
+      // always show foreground even for background commands.
+      const p = args as RunCommandParams;
+      return runtime.runCommand({ ...p, background: p.run_in_background } as never);
+    }
+
+    case 'getCommandOutput': {
+      // Forward `timeout` (gateway per-call budget, injected into args by
+      // executeToolCall) so polling a running command honors it instead of the
+      // service's default wait. The runtime carries it through to getOutput.
+      const p = args as GetCommandOutputParams;
+      return runtime.getCommandOutput({
+        commandId: p.shell_id,
+        filter: p.filter,
+        timeout: p.timeout,
+      } as never);
+    }
+
+    case 'killCommand': {
+      const p = args as KillCommandParams;
+      return runtime.killCommand({ commandId: p.shell_id });
+    }
+
+    default: {
+      return null;
+    }
+  }
+}

apps/cli/src/utils/agentStream.ts

@@ -296,7 +296,11 @@ export async function streamAgentEventsViaWebSocket(
         console.log(JSON.stringify(jsonEvents, null, 2));
       }
       isSettled = true;
-      reject(new Error(`Agent gateway WebSocket closed before completion: ${String(event)}`));
+      // Surface the close code + reason — `String(event)` is just "[object CloseEvent]".
+      const reason = event.reason ? `: ${event.reason}` : '';
+      reject(
+        new Error(`Agent gateway WebSocket closed before completion (code ${event.code}${reason})`),
+      );
     };
   });
 }

apps/cli/tsconfig.json

@@ -15,6 +15,7 @@
     "paths": {
       "@lobechat/device-gateway-client": ["../../packages/device-gateway-client/src"],
       "@lobechat/local-file-shell": ["../../packages/local-file-shell/src"],
+      "@lobechat/tool-runtime": ["../../packages/tool-runtime/src"],
       "@/*": ["../../src/*"]
     }
   },

apps/cli/vitest.config.mts

@@ -17,6 +17,10 @@ export default defineConfig({
         find: '@lobechat/file-loaders',
         replacement: path.resolve(__dirname, '../../packages/file-loaders/src/index.ts'),
       },
+      {
+        find: '@lobechat/tool-runtime',
+        replacement: path.resolve(__dirname, '../../packages/tool-runtime/src/index.ts'),
+      },
     ],
   },
   test: {

apps/desktop/electron.vite.config.ts

@@ -223,5 +223,19 @@ export default defineConfig({
       dedupe: ['react', 'react-dom'],
       tsconfigPaths: true,
     },
+    // In dev the BrowserWindow loads `app://renderer/` and the Electron main process
+    // proxies non-backend requests to this Vite dev server via `net.fetch`. The HMR
+    // WebSocket still connects directly (browser → ws://localhost:<port>) — so the
+    // port MUST be deterministic. `strictPort` fails fast on conflict instead of
+    // silently sliding, and `clientPort` baked into the HMR injection has to match.
+    server: {
+      hmr: {
+        clientPort: 5173,
+        host: 'localhost',
+        protocol: 'ws',
+      },
+      port: 5173,
+      strictPort: true,
+    },
   },
 });

apps/desktop/package.json

@@ -54,13 +54,16 @@
     "@electron-toolkit/preload": "^3.0.2",
     "@electron-toolkit/tsconfig": "^2.0.0",
     "@electron-toolkit/utils": "^4.0.0",
+    "@lobechat/chat-adapter-imessage": "workspace:*",
     "@lobechat/desktop-bridge": "workspace:*",
     "@lobechat/device-gateway-client": "workspace:*",
+    "@lobechat/device-identity": "workspace:*",
     "@lobechat/electron-client-ipc": "workspace:*",
     "@lobechat/electron-server-ipc": "workspace:*",
     "@lobechat/file-loaders": "workspace:*",
     "@lobechat/heterogeneous-agents": "workspace:*",
     "@lobechat/local-file-shell": "workspace:*",
+    "@lobechat/tool-runtime": "workspace:*",
     "@lobehub/i18n-cli": "^1.25.1",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@t3-oss/env-core": "^0.13.8",
@@ -75,7 +78,7 @@
     "cross-env": "^10.1.0",
     "diff": "^8.0.4",
     "electron": "41.3.0",
-    "electron-builder": "^26.8.1",
+    "electron-builder": "26.14.0",
     "electron-devtools-installer": "4.0.0",
     "electron-is": "^3.0.0",
     "electron-store": "^8.2.0",
@@ -108,7 +111,7 @@
     "undici": "^7.16.0",
     "uuid": "^14.0.0",
     "vite": "8.0.14",
-    "vitest": "^3.2.4",
+    "vitest": "3.2.4",
     "zod": "^3.25.76"
   },
   "optionalDependencies": {
@@ -123,7 +126,8 @@
     ],
     "overrides": {
       "react": "19.2.4",
-      "react-dom": "19.2.4"
+      "react-dom": "19.2.4",
+      "vitest": "3.2.4"
     }
   }
 }

apps/desktop/pnpm-workspace.yaml

@@ -1,6 +1,7 @@
 packages:
   - '../cli'
   - '../../packages/agent-gateway-client'
+  - '../../packages/chat-adapter-imessage'
   - '../../packages/heterogeneous-agents'
   - '../../packages/const'
   - '../../packages/electron-server-ipc'
@@ -8,7 +9,10 @@ packages:
   - '../../packages/file-loaders'
   - '../../packages/desktop-bridge'
   - '../../packages/device-gateway-client'
+  - '../../packages/device-identity'
   - '../../packages/local-file-shell'
+  - '../../packages/tool-runtime'
+  - '../../packages/prompts'
   - './stubs/business-const'
   - './stubs/types'
   - '.'

apps/desktop/resources/locales/zh-CN/menu.json

@@ -56,9 +56,11 @@
   "help.about": "关于",
   "help.githubRepo": "GitHub 仓库",
   "help.openConfigDir": "配置目录",
+  "help.openHeteroAgentDir": "打开 HeteroAgent 目录",
   "help.openLogsDir": "打开日志目录",
   "help.reportIssue": "反馈问题",
   "help.title": "帮助",
+  "help.toggleHeteroTracing": "记录 Agent CLI 调试日志",
   "help.visitWebsite": "打开官网",
   "history.back": "后退",
   "history.forward": "前进",